@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/nm-auto-apn.ts

@@ -1,161 +0,0 @@
-// Auto-APN: boot capability probe, the two atomic transition argv builders, and the
-// activation-result classifier.
-//
-// Auto-APN (`apn:"auto"` ⇒ NM `gsm.auto-config yes`) needs NetworkManager >= 1.22
-// (bookworm ships 1.42). A boot capability probe reads nmcli's version — replacing any
-// implicit/hardcoded gating — and when NM is too old an auto policy resolves to
-// `unsupported` up front with the `autoApnUnavailable` advisory (no modify at all).
-//
-// When NM DOES support auto-config a bad/unknown SIM can still have no MBPI match: the
-// connection fails to activate with a GSM_APN_FAILED device-state reason. That is
-// classified at ACTIVATION, not guessed ahead of time — reactivate the exact
-// (uuid, ifname) pair, await the terminal state, then:
-//   GSM_APN_FAILED under an auto profile → unsupported + autoApnUnavailable advisory
-//   any other activation error            → failed
-//   nmcli's own activation wait timed out → pending
-
-import { type Receipt, receipt } from '../ports';
-import { cliArg, passwordFlags } from './nm-gsm-fields';
-import { type NmcliResult, type NmcliRunner, runNmcli } from './nmcli-runner';
-
-/** The single advisory Auto-APN raises when it cannot be honored. */
-export const AUTO_APN_ADVISORY = 'autoApnUnavailable';
-export type AutoApnAdvisory = typeof AUTO_APN_ADVISORY;
-
-/** The outcome of an Auto-APN transition: a receipt plus an optional advisory flag. */
-export interface AutoApnTransitionResult {
-	readonly receipt: Receipt;
-	readonly advisory?: AutoApnAdvisory;
-}
-
-/** Explicit APN + credentials for the manual direction of a transition. */
-export interface ManualApn {
-	readonly apn: string;
-	readonly username?: string;
-	readonly password?: string;
-}
-
-const AUTO_CONFIG_MIN_MAJOR = 1;
-const AUTO_CONFIG_MIN_MINOR = 22;
-
-/** nmcli's own `--wait` timeout exit status (nmcli(1): 3 = timeout expired). */
-const NMCLI_EXIT_TIMEOUT = 3;
-
-const APN_FAILED = /gsm[_-]?apn[_-]?failed/i;
-
-/** Parse `nmcli tool, version 1.42.4` → `{ major, minor }` (null on garbage). */
-export function parseNmVersion(output: string): { major: number; minor: number } | null {
-	const match = /version\s+(\d+)\.(\d+)/i.exec(output);
-	if (match?.[1] === undefined || match[2] === undefined) {
-		return null;
-	}
-	return { major: Number(match[1]), minor: Number(match[2]) };
-}
-
-/** `true` iff the parsed NM version is >= 1.22 (auto-config support floor). */
-export function autoApnSupportedByVersion(version: { major: number; minor: number }): boolean {
-	if (version.major !== AUTO_CONFIG_MIN_MAJOR) {
-		return version.major > AUTO_CONFIG_MIN_MAJOR;
-	}
-	return version.minor >= AUTO_CONFIG_MIN_MINOR;
-}
-
-/**
- * Decide from a `nmcli --version` result whether Auto-APN is available on this install.
- * Fail-CLOSED — an unreadable/garbled version is "not capable", so we never claim
- * Auto-APN works when we cannot prove it does.
- */
-export function autoApnCapableFromVersion(result: NmcliResult): boolean {
-	if (result.exitCode !== 0) {
-		return false;
-	}
-	const version = parseNmVersion(result.stdout);
-	return version !== null && autoApnSupportedByVersion(version);
-}
-
-/** Boot capability probe: run `nmcli --version` and resolve Auto-APN availability. */
-export async function probeAutoApnCapability(runner: NmcliRunner): Promise<boolean> {
-	return autoApnCapableFromVersion(await runNmcli(runner, ['--version']));
-}
-
-/**
- * ONE atomic `connection modify` that flips a profile to Auto-APN: clears every
- * credential AND sets `gsm.auto-config yes` in the SAME invocation. Order/atomicity
- * matter — NM rejects `auto-config yes` while any credential is still set, so the clear
- * and the enable MUST land together (never two modifies).
- */
-export function toAutoArgs(id: string): string[] {
-	return [
-		'connection',
-		'modify',
-		id,
-		'gsm.apn',
-		'',
-		'gsm.username',
-		'',
-		'gsm.password',
-		'',
-		'gsm.password-flags',
-		'4',
-		'gsm.auto-config',
-		'yes',
-	];
-}
-
-/**
- * The exact reverse: ONE atomic `connection modify` restoring explicit APN + creds and
- * clearing `gsm.auto-config`, with password-flags matching the (new) password.
- */
-export function toManualArgs(id: string, creds: ManualApn): string[] {
-	return [
-		'connection',
-		'modify',
-		id,
-		'gsm.apn',
-		cliArg(creds.apn),
-		'gsm.username',
-		cliArg(creds.username),
-		'gsm.password',
-		cliArg(creds.password),
-		'gsm.password-flags',
-		passwordFlags(creds.password),
-		'gsm.auto-config',
-		'no',
-	];
-}
-
-/**
- * Classify a `connection up` result into a receipt (+ advisory). `underAuto` marks that
- * the profile being activated is an Auto-APN profile, so an APN failure is the "no MBPI
- * match for this SIM" case → unsupported + advisory rather than a hard fail.
- */
-export function classifyActivation(
-	result: NmcliResult,
-	options: { readonly underAuto: boolean },
-): AutoApnTransitionResult {
-	if (result.exitCode === 0) {
-		return { receipt: receipt('connection', 'applied', 'connection activated') };
-	}
-	if (result.exitCode === NMCLI_EXIT_TIMEOUT || /timeout/i.test(result.stderr)) {
-		return {
-			receipt: receipt(
-				'connection',
-				'pending',
-				'activation wait timed out; terminal state unknown',
-			),
-		};
-	}
-	if (options.underAuto && (APN_FAILED.test(result.stderr) || APN_FAILED.test(result.stdout))) {
-		return {
-			receipt: receipt(
-				'connection',
-				'unsupported',
-				'Auto-APN found no operator match for this SIM',
-			),
-			advisory: AUTO_APN_ADVISORY,
-		};
-	}
-	return {
-		receipt: receipt('connection', 'failed', result.stderr || 'connection activation failed'),
-	};
-}

package/src/backend/nm-gsm-fields.ts

@@ -1,122 +0,0 @@
-// Pure nmcli GSM-connection argv builders — the FULL nine-field write parity today's
-// CeraUI carried (modem-registration.ts `sanitizeModemConfigForNetworkManager` +
-// `addConnectionForModem`), rebuilt from scratch for the device-exact adapter so the
-// greenfield port loses nothing the wrap-first path wrote.
-//
-// The nine fields and their exact NM conventions (`gsm.*` + `connection.*` setting
-// semantics) are the contract A4.1 must not regress:
-//   gsm.apn / gsm.username / gsm.password  — creds ("" when unset)
-//   gsm.password-flags                     — "4" NOT_REQUIRED (no password),
-//                                            "0" NONE / system-stored (password set)
-//   gsm.home-only                          — "yes" ⇒ roaming DISABLED
-//   gsm.network-id                         — manual operator PLMN, only while roaming
-//   gsm.auto-config                        — "yes" ⇒ Auto-APN (creds MUST be empty)
-//   connection.autoconnect                 — always "yes"
-//   connection.autoconnect-retries         — "2"
-
-import type { ConnectionId, GsmProfile, GsmProfileInput, GsmProfilePatch } from '../ports';
-
-// Empty-string fallback; Bun runtime limitation with empty CLI args: a bare
-// `undefined` reaching `Bun.spawn` argv drops the slot and shifts every following
-// token, so every optional nmcli value is coerced to "" first — the same `value || ""`
-// convention CeraUI documented on gsm.apn / gsm.username / gsm.password.
-export const cliArg = (value: string | undefined): string => value || '';
-
-/** NM secret-flags: no password ⇒ NOT_REQUIRED ("4"); password set ⇒ NONE ("0"). */
-export const passwordFlags = (password: string | undefined): string => (password ? '0' : '4');
-
-/** `gsm.network-id` — the manual operator id, and only while roaming (home-only off). */
-const networkIdField = (input: GsmProfileInput): string =>
-	input.homeOnly ? '' : cliArg(input.networkId);
-
-/**
- * The nine `gsm.*` + `connection.*` key/value pairs for a profile, in stable order.
- * With `autoConfig` set the creds are forced empty (NM rejects `auto-config yes` while
- * any credential is present — nm-setting-gsm.c:440-447), so an Auto-APN create is always
- * NM-valid by construction.
- */
-export function gsmFieldPairs(input: GsmProfileInput): Array<[string, string]> {
-	const auto = input.autoConfig;
-	return [
-		['gsm.apn', auto ? '' : cliArg(input.apn)],
-		['gsm.username', auto ? '' : cliArg(input.username)],
-		['gsm.password', auto ? '' : cliArg(input.password)],
-		['gsm.password-flags', passwordFlags(auto ? undefined : input.password)],
-		['gsm.home-only', input.homeOnly ? 'yes' : 'no'],
-		['gsm.network-id', networkIdField(input)],
-		['gsm.auto-config', auto ? 'yes' : 'no'],
-		['connection.autoconnect', 'yes'],
-		['connection.autoconnect-retries', '2'],
-	];
-}
-
-/** Flatten key/value pairs into the alternating argv nmcli expects. */
-export function flattenPairs(pairs: ReadonlyArray<readonly [string, string]>): string[] {
-	return pairs.flat();
-}
-
-/** `connection add type gsm con-name <name> <nine fields>` — device-exact create argv. */
-export function createGsmArgs(input: GsmProfileInput): string[] {
-	return [
-		'connection',
-		'add',
-		'type',
-		'gsm',
-		'con-name',
-		input.connectionName,
-		...flattenPairs(gsmFieldPairs(input)),
-	];
-}
-
-/**
- * The key/value pairs for a `connection modify`. Roaming (home-only) and the manual
- * operator id move together — turning roaming off clears `gsm.network-id`, honoring the
- * `gsm.network-id = roaming ? id : ""` invariant in the SAME modify.
- */
-export function patchPairs(patch: GsmProfilePatch): string[] {
-	const pairs: string[] = [];
-	if (patch.connectionName !== undefined) {
-		pairs.push('connection.id', patch.connectionName);
-	}
-	if (patch.apn !== undefined) {
-		pairs.push('gsm.apn', cliArg(patch.apn));
-	}
-	if (patch.username !== undefined) {
-		pairs.push('gsm.username', cliArg(patch.username));
-	}
-	if (patch.password !== undefined) {
-		pairs.push(
-			'gsm.password',
-			cliArg(patch.password),
-			'gsm.password-flags',
-			passwordFlags(patch.password),
-		);
-	}
-	if (patch.autoConfig !== undefined) {
-		pairs.push('gsm.auto-config', patch.autoConfig ? 'yes' : 'no');
-	}
-	if (patch.homeOnly !== undefined) {
-		pairs.push('gsm.home-only', patch.homeOnly ? 'yes' : 'no');
-		pairs.push('gsm.network-id', patch.homeOnly ? '' : cliArg(patch.networkId));
-	} else if (patch.networkId !== undefined) {
-		pairs.push('gsm.network-id', cliArg(patch.networkId));
-	}
-	return pairs;
-}
-
-/** Map an nmcli terse readback back onto a `GsmProfile` (inverse of the write parity). */
-export function buildProfile(id: ConnectionId, settings: Map<string, string>): GsmProfile {
-	const username = settings.get('gsm.username') ?? '';
-	const password = settings.get('gsm.password') ?? '';
-	const networkId = settings.get('gsm.network-id') ?? '';
-	return {
-		connectionId: id,
-		connectionName: settings.get('connection.id') ?? '',
-		apn: settings.get('gsm.apn') ?? '',
-		homeOnly: settings.get('gsm.home-only') === 'yes',
-		autoConfig: settings.get('gsm.auto-config') === 'yes',
-		...(username !== '' ? { username } : {}),
-		...(password !== '' ? { password } : {}),
-		...(networkId !== '' ? { networkId } : {}),
-	};
-}

package/src/backend/nmcli-nm-port.ts

@@ -1,228 +0,0 @@
-// The device-exact NetworkManager adapter: a FRESH nmcli-based `NetworkManagerPort`
-// (no reused CeraUI code) with the full nine-field GSM write parity, verify-then-
-// device-disconnect deactivation (never id-only `connection down`), abandoned-lease
-// quiesce, and atomic Auto-APN transitions.
-
-import { epochMillis } from '../domain';
-import {
-	type ConnectionId,
-	connectionId,
-	type DeviceIfname,
-	type GsmProfile,
-	type GsmProfileInput,
-	type GsmProfilePatch,
-	type NetworkManagerPort,
-	type QuiesceLease,
-	type Receipt,
-	receipt,
-} from '../ports';
-import {
-	AUTO_APN_ADVISORY,
-	type AutoApnTransitionResult,
-	classifyActivation,
-	type ManualApn,
-	toAutoArgs,
-	toManualArgs,
-} from './nm-auto-apn';
-import { buildProfile, createGsmArgs, patchPairs } from './nm-gsm-fields';
-import { type NmcliResult, type NmcliRunner, parseTerse, runNmcli } from './nmcli-runner';
-
-const READBACK_FIELDS = [
-	'connection.id',
-	'gsm.apn',
-	'gsm.username',
-	'gsm.password',
-	'gsm.password-flags',
-	'gsm.home-only',
-	'gsm.network-id',
-	'gsm.auto-config',
-	'connection.autoconnect',
-	'connection.autoconnect-retries',
-];
-
-/** Default abandoned-lease TTL: a held quiesce lease older than this auto-releases. */
-const DEFAULT_LEASE_TTL_MS = 60_000;
-
-export interface NmcliNmPortOptions {
-	readonly runner: NmcliRunner;
-	/** Resolved once at boot by the capability probe; default `true`. */
-	readonly autoApnCapable?: boolean;
-	readonly leaseTtlMs?: number;
-	readonly now?: () => number;
-}
-
-export class NmcliNmPort implements NetworkManagerPort {
-	readonly #runner: NmcliRunner;
-	readonly #autoApnCapable: boolean;
-	readonly #leaseTtlMs: number;
-	readonly #now: () => number;
-	readonly #leases = new Set<QuiesceLease>();
-
-	constructor(options: NmcliNmPortOptions) {
-		this.#runner = options.runner;
-		this.#autoApnCapable = options.autoApnCapable ?? true;
-		this.#leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
-		this.#now = options.now ?? Date.now;
-	}
-
-	async createGsmProfile(profile: GsmProfileInput): Promise<GsmProfile> {
-		const result = await runNmcli(this.#runner, createGsmArgs(profile));
-		const uuid = /\(([^)]+)\) successfully added/.exec(result.stdout)?.[1];
-		if (uuid === undefined) {
-			throw new Error(`nmcli connection add failed: ${result.stderr || result.stdout}`);
-		}
-		return this.#requireProfile(connectionId(uuid));
-	}
-
-	async readGsmProfile(id: ConnectionId): Promise<GsmProfile | undefined> {
-		const result = await runNmcli(this.#runner, [
-			'-t',
-			'-f',
-			READBACK_FIELDS.join(','),
-			'connection',
-			'show',
-			id,
-		]);
-		if (result.exitCode !== 0) {
-			return undefined;
-		}
-		return buildProfile(id, parseTerse(result.stdout));
-	}
-
-	async updateGsmProfile(id: ConnectionId, patch: GsmProfilePatch): Promise<GsmProfile> {
-		const result = await runNmcli(this.#runner, ['connection', 'modify', id, ...patchPairs(patch)]);
-		if (result.exitCode !== 0) {
-			throw new Error(`nmcli connection modify failed: ${result.stderr}`);
-		}
-		return this.#requireProfile(id);
-	}
-
-	async deleteGsmProfile(id: ConnectionId): Promise<void> {
-		await runNmcli(this.#runner, ['connection', 'delete', id]);
-	}
-
-	async activate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt> {
-		const result = await runNmcli(this.#runner, ['connection', 'up', id, 'ifname', ifname]);
-		return activationReceipt(result, `activated ${id} on ${ifname}`);
-	}
-
-	async deactivate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt> {
-		if ((await this.#activeUuidOn(ifname)) !== id) {
-			return receipt('enabled', 'applied', `${id} not active on ${ifname}; nothing to deactivate`);
-		}
-		const result = await runNmcli(this.#runner, ['device', 'disconnect', ifname]);
-		return activationReceipt(result, `deactivated ${id} on ${ifname}`);
-	}
-
-	async acquireQuiesceLease(id: ConnectionId, ifname: DeviceIfname): Promise<QuiesceLease> {
-		if ((await this.#activeUuidOn(ifname)) === id) {
-			await runNmcli(this.#runner, ['device', 'disconnect', ifname]);
-		}
-		const lease: QuiesceLease = {
-			connectionId: id,
-			deviceIfname: ifname,
-			acquiredAt: epochMillis(this.#now()),
-		};
-		this.#leases.add(lease);
-		return lease;
-	}
-
-	async releaseQuiesceLease(lease: QuiesceLease): Promise<void> {
-		if (this.#leases.delete(lease)) {
-			await this.#reactivate(lease);
-		}
-	}
-
-	/** Reactivate every lease held past the TTL — the abandoned-lease watchdog. */
-	async sweepExpiredLeases(now: number = this.#now()): Promise<void> {
-		for (const lease of [...this.#leases]) {
-			if (now - lease.acquiredAt >= this.#leaseTtlMs) {
-				this.#leases.delete(lease);
-				await this.#reactivate(lease);
-			}
-		}
-	}
-
-	/** Flip a profile to Auto-APN via ONE atomic modify, then reactivate + classify. */
-	async transitionToAuto(id: ConnectionId, ifname: DeviceIfname): Promise<AutoApnTransitionResult> {
-		if (!this.#autoApnCapable) {
-			return {
-				receipt: receipt('connection', 'unsupported', 'Auto-APN requires NetworkManager >= 1.22'),
-				advisory: AUTO_APN_ADVISORY,
-			};
-		}
-		const modify = await runNmcli(this.#runner, toAutoArgs(id));
-		if (modify.exitCode !== 0) {
-			return {
-				receipt: receipt('connection', 'failed', modify.stderr || 'auto-config modify rejected'),
-			};
-		}
-		return this.#reactivateAndClassify(id, ifname, true);
-	}
-
-	/** Flip a profile to manual APN via ONE atomic modify, then reactivate + classify. */
-	async transitionToManual(
-		id: ConnectionId,
-		ifname: DeviceIfname,
-		creds: ManualApn,
-	): Promise<AutoApnTransitionResult> {
-		const modify = await runNmcli(this.#runner, toManualArgs(id, creds));
-		if (modify.exitCode !== 0) {
-			return {
-				receipt: receipt('connection', 'failed', modify.stderr || 'manual-apn modify rejected'),
-			};
-		}
-		return this.#reactivateAndClassify(id, ifname, false);
-	}
-
-	async #reactivateAndClassify(
-		id: ConnectionId,
-		ifname: DeviceIfname,
-		underAuto: boolean,
-	): Promise<AutoApnTransitionResult> {
-		const up = await runNmcli(this.#runner, ['connection', 'up', id, 'ifname', ifname]);
-		return classifyActivation(up, { underAuto });
-	}
-
-	async #reactivate(lease: QuiesceLease): Promise<void> {
-		await runNmcli(this.#runner, [
-			'connection',
-			'up',
-			lease.connectionId,
-			'ifname',
-			lease.deviceIfname,
-		]);
-	}
-
-	async #activeUuidOn(ifname: DeviceIfname): Promise<string | undefined> {
-		const result = await runNmcli(this.#runner, [
-			'-t',
-			'-f',
-			'UUID,DEVICE',
-			'connection',
-			'show',
-			'--active',
-		]);
-		for (const line of result.stdout.split('\n')) {
-			const [uuid, device] = line.split(':');
-			if (device === ifname && uuid) {
-				return uuid;
-			}
-		}
-		return undefined;
-	}
-
-	async #requireProfile(id: ConnectionId): Promise<GsmProfile> {
-		const profile = await this.readGsmProfile(id);
-		if (profile === undefined) {
-			throw new Error(`nmcli: profile ${id} did not read back`);
-		}
-		return profile;
-	}
-}
-
-function activationReceipt(result: NmcliResult, appliedReason: string): Receipt {
-	return result.exitCode === 0
-		? receipt('enabled', 'applied', appliedReason)
-		: receipt('enabled', 'failed', result.stderr || 'nmcli returned a non-zero exit code');
-}

package/src/backend/nmcli-runner.ts

@@ -1,52 +0,0 @@
-// The nmcli invocation seam. The shipping adapter spawns the real `nmcli`; tests
-// inject A2.3's stateful in-memory runner (structurally the same `run(argv)`). The
-// port never spawns directly — it only ever talks to an injected `NmcliRunner`, so
-// the exact code path exercised under test is the one that runs on-device.
-
-export interface NmcliResult {
-	readonly stdout: string;
-	readonly stderr: string;
-	readonly exitCode: number;
-}
-
-/**
- * A runner over nmcli argv. `run` may be synchronous (the stateful test double) or
- * asynchronous (the real `Bun.spawn` adapter) — the port awaits either way.
- */
-export interface NmcliRunner {
-	run(argv: readonly string[]): NmcliResult | Promise<NmcliResult>;
-}
-
-/** Await a runner's result whether it returned synchronously or as a promise. */
-export async function runNmcli(runner: NmcliRunner, argv: readonly string[]): Promise<NmcliResult> {
-	return runner.run(argv);
-}
-
-/**
- * The device-exact runner: spawns the real `nmcli` via Bun. Every argv the port
- * builds is passed verbatim, so what the tests assert against the stateful stub is
- * byte-for-byte what runs on the device.
- */
-export class SpawnNmcliRunner implements NmcliRunner {
-	async run(argv: readonly string[]): Promise<NmcliResult> {
-		const proc = Bun.spawn(['nmcli', ...argv], { stdout: 'pipe', stderr: 'pipe' });
-		const [stdout, stderr, exitCode] = await Promise.all([
-			new Response(proc.stdout).text(),
-			new Response(proc.stderr).text(),
-			proc.exited,
-		]);
-		return { stdout, stderr, exitCode };
-	}
-}
-
-/** Parse nmcli terse (`-t`) `key:value` lines into a map, splitting on the first `:`. */
-export function parseTerse(stdout: string): Map<string, string> {
-	const settings = new Map<string, string>();
-	for (const line of stdout.split('\n')) {
-		const separator = line.indexOf(':');
-		if (separator >= 0) {
-			settings.set(line.slice(0, separator), line.slice(separator + 1));
-		}
-	}
-	return settings;
-}