@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/devices/stats-cache.js

@@ -1,65 +1,12 @@
-/**
- * Disk cache for fleet {@link DeviceStats} so `agents devices list` and
- * `agents fleet status` render instantly from the last probe instead of
- * live-SSHing every registered box on every invocation.
- *
- * The old behaviour probed the whole fleet over ssh on every call
- * ({@link probeFleetStats}) — with a dozen devices, a few of them cold or
- * timing out, that turned a status glance into a multi-second hang. This module
- * makes the reads cache-first:
- *
- * - **Default:** serve remote devices from the cache (instant); always probe
- *   *this* machine locally (no ssh, sub-ms) so the "this machine" row is live;
- *   probe only the remote devices missing from the cache (first run / a
- *   newly-added box), then persist them.
- * - **`--refresh` / `--live`:** skip the cache and live-probe every device,
- *   rewriting the cache.
- *
- * Every cached row is bounded by {@link STATS_STALE_MS}: a row older than the
- * window is treated exactly like a missing one — re-probed live this call and
- * rewritten — so the default read is itself the cache's writer and a value can
- * never fossilize at the last manual `--refresh`. (The daemon used to warm this
- * cache every ~3 min; RUSH-2061 removed that N² fleet probe, which left the
- * unbounded read serving multi-day-old rows as current fleet state — the
- * scheduler, `--device auto`, and the session-start banner all read these
- * numbers. See #2666.)
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from '../state.js';
 import { probeFleetStats, probeLocalStats } from './health.js';
 const CACHE_FILE = '.fleet-stats.json';
-/**
- * Freshness bound for a cached row. Matches the agent-count mirror's window
- * (`AGENT_STATUS_STALE_MS` in `commands/ssh.ts`) so both columns of
- * `devices list` / `fleet status` share one staleness model. A row older than
- * this is never served as current — it is re-probed live (and the probe result
- * rewrites the cache, unreachable boxes included).
- */
 export const STATS_STALE_MS = 3 * 60_000;
-/** True when a cached row is still within {@link STATS_STALE_MS}. */
 export function isFreshDeviceStats(stats, now = Date.now()) {
     return now - stats.fetchedAt <= STATS_STALE_MS;
 }
-/**
- * Carry a device's last successfully-probed hardware facts onto a row whose
- * probe just came back unreachable (RUSH-3096).
- *
- * A failed probe knows nothing about the box — `probeDeviceStats` resolves
- * `{ host, reachable: false, fetchedAt }` — and that bare row then replaced the
- * cached one, so `agents devices list` rendered an offline device with an empty
- * `spec` cell and forgot its cores/RAM/disk until it came back up. Cores, total
- * RAM, and root-disk capacity do not change while a machine is down, so they
- * survive the failure; `loadPercent`, `memPercent`, and the free-byte counts are
- * current-state readings and stay absent rather than render a stale number as
- * live.
- *
- * `specsFetchedAt` keeps the moment the facts were actually observed while
- * `fetchedAt` advances to this attempt, so the row reads "this hardware, seen
- * then; unreachable, as of now" instead of backdating a reading that never
- * happened. A reachable probe is returned untouched — its own reading is the
- * truth, including a fact the box has stopped reporting.
- */
 export function retainHardwareFacts(probed, prior) {
     if (probed.reachable || !prior)
         return probed;
@@ -82,7 +29,6 @@ export function retainHardwareFacts(probed, prior) {
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
-/** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export function readStatsCache() {
     try {
         const parsed = JSON.parse(fs.readFileSync(cacheFilePath(), 'utf-8'));
@@ -90,15 +36,9 @@ export function readStatsCache() {
             return parsed.entries;
     }
     catch {
-        // missing or corrupt — treat as empty
     }
     return {};
 }
-/**
- * Merge freshly-probed rows into the on-disk cache (best-effort write). Rows for
- * devices not in `entries` are preserved, so a partial probe (gap-fill, or a
- * single-device refresh) never drops the rest of the fleet's cached stats.
- */
 export function writeStatsCache(entries) {
     try {
         const dir = getCacheDir();
@@ -111,10 +51,8 @@ export function writeStatsCache(entries) {
         fs.writeFileSync(cacheFilePath(), JSON.stringify(merged, null, 2));
     }
     catch {
-        // best-effort; a failed write just means the next read falls back to a live probe
     }
 }
-/** Drop one removed device so cache-only rows cannot outlive the registry. */
 export function removeStatsCacheEntry(name) {
     try {
         const current = readStatsCache();
@@ -124,20 +62,13 @@ export function removeStatsCacheEntry(name) {
         fs.writeFileSync(cacheFilePath(), JSON.stringify({ version: 1, entries }, null, 2));
     }
     catch {
-        // Cache cleanup is best-effort; registry removal remains authoritative.
     }
 }
-/** Immutable cache pruning primitive, exported for lifecycle regression tests. */
 export function pruneStatsCache(entries, name) {
     const { [name]: _removed, ...remaining } = entries;
     void _removed;
     return remaining;
 }
-/**
- * Load fleet stats cache-first. See the module doc for the default vs
- * `--refresh` behaviour. Never throws — an unreachable box degrades to a
- * `reachable: false` row exactly as the live probe does.
- */
 export async function loadFleetStats(devices, opts = {}) {
     const probeFleet = opts.probeFleet ?? probeFleetStats;
     const probeLocal = opts.probeLocal ?? probeLocalStats;
@@ -145,16 +76,12 @@ export async function loadFleetStats(devices, opts = {}) {
     const writeCache = opts.writeCache ?? writeStatsCache;
     const self = opts.selfName;
     const now = opts.now ?? Date.now();
-    // Always read the cache, even under --refresh. It is not *served* then, but it
-    // is the only record of each box's hardware, and a failed probe must not erase
-    // it — see {@link retainHardwareFacts}.
     const cache = readCache();
     const stats = new Map();
     const toProbe = [];
     let servedFromCache = false;
     for (const d of devices) {
         if (d.name === self) {
-            // This machine is always probed locally — cheap, no ssh, always live.
             toProbe.push(d);
             continue;
         }
@@ -165,8 +92,6 @@ export async function loadFleetStats(devices, opts = {}) {
             servedFromCache = true;
         }
         else {
-            // Missing OR beyond the staleness bound: a stale number rendered as
-            // current is worse than the probe's cost, so re-probe live (#2666).
             toProbe.push(d);
         }
     }
@@ -174,8 +99,6 @@ export async function loadFleetStats(devices, opts = {}) {
         const probed = await probeFleet(toProbe, { selfName: self });
         const fresh = {};
         for (const [name, s] of probed) {
-            // A box that just failed to answer keeps the hardware it was last seen
-            // with, so this call and the cache it writes both carry the spec.
             const row = retainHardwareFacts(s, cache[name]);
             stats.set(name, row);
             fresh[name] = row;
@@ -183,9 +106,6 @@ export async function loadFleetStats(devices, opts = {}) {
         if (Object.keys(fresh).length > 0)
             writeCache(fresh);
     }
-    // Guarantee a row for this machine even when it isn't in the passed device
-    // list (e.g. self not registered as an ssh target) — matches the old callers'
-    // explicit local fallback.
     if (self && !stats.has(self)) {
         stats.set(self, retainHardwareFacts(await probeLocal(self), cache[self]));
     }

package/dist/lib/devices/sync.d.ts

@@ -1,132 +1,35 @@
 import { type DeviceInput } from './registry.js';
 import { type TailscaleNode } from './tailscale.js';
 import type { PendingDevice } from './pending.js';
-/**
- * The login user to stamp onto newly-synced devices. Tailscale status carries a
- * node's OS and address but NOT the account you ssh in as, so we materialize the
- * local operator's username — tailnet devices are overwhelmingly one person's
- * boxes, and this is exactly the account ssh would already fall back to. Pinning
- * it in the registry makes `--device <device>` dial that account no matter which
- * machine launches the fan-out (a peer whose local user differs otherwise dials
- * the wrong account). Returns undefined when the username isn't a safe ssh
- * identifier, so a weird value never lands in the registry. */
 export declare function localLoginUser(): string | undefined;
-/**
- * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
- * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
- * after the backslash — without this strip the `\` fails the charset guard and
- * Windows boxes never pin a user. Pure, so the platform-specific munging is
- * unit-tested without reading the real OS user. */
 export declare function sanitizeLoginUser(raw: string | undefined): string | undefined;
-/**
- * Fill in a device's login user during sync WITHOUT ever clobbering an account
- * the user pinned. Precedence: an existing registered user wins; else the local
- * operator's username; else leave it unset (ssh's implicit local default still
- * applies). Pure so the "never overwrite an explicit user" guard is unit-tested
- * without a tailnet. */
 export declare function withDefaultUser(input: DeviceInput, prevUser: string | undefined, localUser: string | undefined): DeviceInput;
-/**
- * bootstrap — register every non-ignored node (opt-out). First-run `agents
- *   setup` and manual `agents devices sync`, so the fleet is usable out of box.
- * refresh — only refresh reachability of already-registered nodes; a brand-new
- *   node is NOT auto-added, it is surfaced as `pending` for the user to approve
- *   (opt-in). Ongoing autosync and the daemon probe use this, so newcomers flow
- *   through the menu-bar "NEW DEVICES → Register / Ignore" gate instead of
- *   silently landing in the registry.
- */
 type DeviceSyncMode = 'bootstrap' | 'refresh';
 interface DeviceSyncResult {
-    /** False when discovery could not run (e.g. tailscale absent) in soft mode. */
     ok: boolean;
-    /** Number of tailscale nodes upserted into the registry. */
     synced: number;
-    /** Names upserted, for explicit onboarding surfaces to persist approval. */
     syncedNames: string[];
-    /** Nodes discovered but neither registered-before nor ignored (name+platform). */
     pending: PendingDevice[];
-    /** Populated when ok is false: why discovery was skipped. */
     reason?: string;
 }
-/**
- * The nodes automatic discovery is allowed to see: sharee nodes (shared INTO
- * the tailnet by another user, e.g. a funnel ingress relay) are not the
- * operator's machines, so they must never be bootstrap-registered nor surfaced
- * as pending. Explicit paths (`devices register <name>`, `devices add`, the
- * `fleet:` manifest bootstrap) are deliberate user actions and stay unfiltered.
- * Pure so the policy is unit-testable without a tailnet.
- */
 export declare function discoverableNodes(nodes: TailscaleNode[]): TailscaleNode[];
-/**
- * Default checked-state for a node in the interactive sync picker. Pressing
- * Enter registers every checked node, so "checked" must mean "auto-sync would
- * register this": not dismissed, and not a sharee node — unless the user
- * already deliberately registered that sharee node, in which case Enter must
- * keep the fleet as-is. Pure so the default matrix is unit-testable without a
- * prompt.
- */
 export declare function defaultPickerChecked(node: TailscaleNode, registered: Set<string>, ignored: Set<string>): boolean;
-/**
- * Node names present on the tailnet but neither already in the registry nor on
- * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
- * flag matrix is unit-testable without a live tailnet.
- */
 export declare function computePendingDevices(nodes: TailscaleNode[], registered: Iterable<string>, ignored: Iterable<string>): string[];
-/**
- * Which discovered nodes to upsert this run — the mode-defining decision, pure
- * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
- * In `refresh` mode a node that isn't already registered is skipped too (it
- * stays pending for approval); `bootstrap` includes every non-ignored node.
- */
 export declare function selectNodesToUpsert(nodes: TailscaleNode[], registered: Set<string>, ignored: Set<string>, mode: DeviceSyncMode): TailscaleNode[];
-/**
- * Ingest `tailscale status --json` into the registry. In soft mode a missing
- * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
- * throwing, so callers wiring this into setup/sync never abort the whole run.
- * The `pending` list is computed against the registry state BEFORE this sync so
- * "new" means "not previously registered and not ignored".
- */
 export declare function runDeviceSync(opts?: {
     soft?: boolean;
     mode?: DeviceSyncMode;
 }): Promise<DeviceSyncResult>;
 interface EnsureDevicesResult {
-    /** Names newly resolved from Tailscale and upserted into the registry. */
     registered: string[];
-    /** Names that could not be resolved (not on the tailnet / tailscale absent). */
     unresolved: string[];
 }
-/**
- * Pure decision for `ensureDevicesRegistered`: split the wanted names into those
- * to resolve+register (missing from the registry, present on the tailnet, not
- * ignored) vs. unresolved (missing and either off-tailnet or ignored). Already-
- * registered names need nothing. Pure so the bootstrap's filter matrix is
- * unit-testable without a tailnet or registry writes.
- */
 interface WantedPartition {
     toRegister: string[];
     unresolved: string[];
 }
 export declare function partitionWantedDevices(wanted: string[], registered: Set<string>, tailscaleNames: Set<string>, ignored: Set<string>): WantedPartition;
-/**
- * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
- * manifest wants, register any that aren't in the local registry by resolving
- * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
- * names only, never IPs/usernames) reconstructs its roster with zero committed
- * connection details. Soft by design: a missing tailscale binary or an offline
- * name yields `unresolved` rather than throwing, so `apply` degrades to "these
- * devices aren't reachable yet" instead of aborting. Reuses the same
- * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
- * is identical to a synced one.
- */
 export declare function ensureDevicesRegistered(wantedNames: string[]): Promise<EnsureDevicesResult>;
-/**
- * The register/remove/ignore decision for the interactive curation picker.
- * Pure so the highest-risk reconcile logic is unit-testable without a tailnet
- * or a live prompt. `keep` is the set the user left checked; everything else is
- * dismissed. Checked => register (and un-ignore if it was ignored). Unchecked
- * => remove from the registry if it was there, and ignore it so auto-sync never
- * re-adds it.
- */
 interface DeviceReconciliation {
     toRegister: string[];
     toUnignore: string[];

package/dist/lib/devices/sync.js

@@ -1,31 +1,6 @@
-/**
- * Reusable device discovery.
- *
- * `agents devices sync` was the only thing that ever populated the registry,
- * and it was purely user-invoked — so the registry sat empty until someone
- * remembered to run it. This module extracts the ingest so it can be triggered
- * automatically (from `agents sync` and `agents setup`) without duplicating the
- * tailscale-parse-and-upsert loop, and exposes the pure pending-device diff the
- * curation picker and the menu-bar probe both need.
- *
- * Two failure modes, one function:
- *   - hard (default): the CLI `agents devices sync` action wants a clear error
- *     and a non-zero exit when tailscale is missing.
- *   - soft (`soft: true`): auto-callers must never abort setup/sync because a
- *     machine has no tailscale — they get a result with `ok: false` instead.
- */
 import * as os from 'os';
 import { loadDevices, loadIgnored, upsertDevice, } from './registry.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson, } from './tailscale.js';
-/**
- * The login user to stamp onto newly-synced devices. Tailscale status carries a
- * node's OS and address but NOT the account you ssh in as, so we materialize the
- * local operator's username — tailnet devices are overwhelmingly one person's
- * boxes, and this is exactly the account ssh would already fall back to. Pinning
- * it in the registry makes `--device <device>` dial that account no matter which
- * machine launches the fan-out (a peer whose local user differs otherwise dials
- * the wrong account). Returns undefined when the username isn't a safe ssh
- * identifier, so a weird value never lands in the registry. */
 export function localLoginUser() {
     let u;
     try {
@@ -36,56 +11,23 @@ export function localLoginUser() {
     }
     return sanitizeLoginUser(u);
 }
-/**
- * Reduce a raw OS username to a safe ssh account, or undefined. Windows reports
- * the login as `COMPUTER\user` / `DOMAIN\user`; the ssh account is the bare name
- * after the backslash — without this strip the `\` fails the charset guard and
- * Windows boxes never pin a user. Pure, so the platform-specific munging is
- * unit-tested without reading the real OS user. */
 export function sanitizeLoginUser(raw) {
     if (!raw)
         return undefined;
     const bare = raw.includes('\\') ? raw.slice(raw.lastIndexOf('\\') + 1) : raw;
     return /^[a-zA-Z0-9._-]+$/.test(bare) ? bare : undefined;
 }
-/**
- * Fill in a device's login user during sync WITHOUT ever clobbering an account
- * the user pinned. Precedence: an existing registered user wins; else the local
- * operator's username; else leave it unset (ssh's implicit local default still
- * applies). Pure so the "never overwrite an explicit user" guard is unit-tested
- * without a tailnet. */
 export function withDefaultUser(input, prevUser, localUser) {
     if (input.user || prevUser || !localUser)
         return input;
     return { ...input, user: localUser };
 }
-/**
- * The nodes automatic discovery is allowed to see: sharee nodes (shared INTO
- * the tailnet by another user, e.g. a funnel ingress relay) are not the
- * operator's machines, so they must never be bootstrap-registered nor surfaced
- * as pending. Explicit paths (`devices register <name>`, `devices add`, the
- * `fleet:` manifest bootstrap) are deliberate user actions and stay unfiltered.
- * Pure so the policy is unit-testable without a tailnet.
- */
 export function discoverableNodes(nodes) {
     return nodes.filter((n) => !n.sharee);
 }
-/**
- * Default checked-state for a node in the interactive sync picker. Pressing
- * Enter registers every checked node, so "checked" must mean "auto-sync would
- * register this": not dismissed, and not a sharee node — unless the user
- * already deliberately registered that sharee node, in which case Enter must
- * keep the fleet as-is. Pure so the default matrix is unit-testable without a
- * prompt.
- */
 export function defaultPickerChecked(node, registered, ignored) {
     return !ignored.has(node.name) && (!node.sharee || registered.has(node.name));
 }
-/**
- * Node names present on the tailnet but neither already in the registry nor on
- * the ignore-list — i.e. genuinely new devices worth surfacing. Pure so the
- * flag matrix is unit-testable without a live tailnet.
- */
 export function computePendingDevices(nodes, registered, ignored) {
     const known = new Set(registered);
     const skip = new Set(ignored);
@@ -93,12 +35,6 @@ export function computePendingDevices(nodes, registered, ignored) {
         .map((n) => n.name)
         .filter((name) => !known.has(name) && !skip.has(name));
 }
-/**
- * Which discovered nodes to upsert this run — the mode-defining decision, pure
- * so it is unit-testable without a tailnet. Ignored nodes are always skipped.
- * In `refresh` mode a node that isn't already registered is skipped too (it
- * stays pending for approval); `bootstrap` includes every non-ignored node.
- */
 export function selectNodesToUpsert(nodes, registered, ignored, mode) {
     return nodes.filter((n) => {
         if (ignored.has(n.name))
@@ -108,20 +44,8 @@ export function selectNodesToUpsert(nodes, registered, ignored, mode) {
         return true;
     });
 }
-/**
- * Ingest `tailscale status --json` into the registry. In soft mode a missing
- * tailscale binary / unreachable daemon resolves to `{ ok: false }` instead of
- * throwing, so callers wiring this into setup/sync never abort the whole run.
- * The `pending` list is computed against the registry state BEFORE this sync so
- * "new" means "not previously registered and not ignored".
- */
 export async function runDeviceSync(opts = {}) {
     const mode = opts.mode ?? 'bootstrap';
-    // Soft mode must be non-fatal for ANY failure, not just a missing tailscale:
-    // a corrupted registry/ignore file (both throw by design), a disk error, or
-    // registry lock contention (plausible when many agents SessionStart-autosync
-    // the same host at once) would otherwise abort the whole `agents sync`. The
-    // whole body is inside the guard so the "never a sync failure" promise holds.
     try {
         const nodes = discoverableNodes(parseTailscaleStatus(tailscaleStatusJson()));
         const [registeredBefore, ignored] = await Promise.all([loadDevices(), loadIgnored()]);
@@ -159,17 +83,6 @@ export function partitionWantedDevices(wanted, registered, tailscaleNames, ignor
     }
     return out;
 }
-/**
- * Fresh-machine bootstrap for `agents apply`: given the device names a `fleet:`
- * manifest wants, register any that aren't in the local registry by resolving
- * them LIVE from Tailscale — so a freshly-cloned `agents.yaml` (which carries
- * names only, never IPs/usernames) reconstructs its roster with zero committed
- * connection details. Soft by design: a missing tailscale binary or an offline
- * name yields `unresolved` rather than throwing, so `apply` degrades to "these
- * devices aren't reachable yet" instead of aborting. Reuses the same
- * parse→withDefaultUser→upsert path as `runDeviceSync`, so a bootstrapped device
- * is identical to a synced one.
- */
 export async function ensureDevicesRegistered(wantedNames) {
     const registryBefore = await loadDevices();
     const registered = new Set(Object.keys(registryBefore));
@@ -181,7 +94,6 @@ export async function ensureDevicesRegistered(wantedNames) {
         nodes = parseTailscaleStatus(tailscaleStatusJson());
     }
     catch {
-        // Tailscale absent/unreachable — nothing resolvable; report all missing.
         return { registered: [], unresolved: missing };
     }
     const ignored = await loadIgnored();

package/dist/lib/devices/tailscale.d.ts

@@ -1,5 +1,4 @@
 import { type DeviceInput, type DevicePlatform } from './registry.js';
-/** A single node distilled from `tailscale status --json`. */
 export interface TailscaleNode {
     name: string;
     platform: DevicePlatform;
@@ -9,26 +8,9 @@ export interface TailscaleNode {
     direct: boolean;
     relay?: string;
     lastSeen?: string;
-    /** True for a node another user shared INTO this tailnet — not the operator's
-     * own machine, so discovery must never auto-register or suggest it. */
     sharee: boolean;
 }
-/**
- * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
- * charset). Used only as a fallback — when a node has a DNSName we prefer its
- * first label, which is the canonical slug Tailscale itself derived.
- */
 export declare function slugifyHostName(hostName: string): string;
-/**
- * Parse `tailscale status --json` output into one node per tailnet device,
- * including Self. Throws on malformed JSON. Nodes without a HostName are
- * skipped (they cannot be addressed by a logical name).
- */
 export declare function parseTailscaleStatus(json: string): TailscaleNode[];
-/** Turn a parsed Tailscale node into the registry fields it can populate. */
 export declare function nodeToDeviceInput(node: TailscaleNode): DeviceInput;
-/**
- * Run `tailscale status --json` and return its raw stdout. Throws a clear
- * error when the binary is missing or the daemon is not reachable.
- */
 export declare function tailscaleStatusJson(): string;

package/dist/lib/devices/tailscale.js

@@ -1,47 +1,22 @@
-/**
- * Tailscale ingestion for the device registry.
- *
- * `tailscale status --json` already hands us most of a device registry for
- * free — per node: `OS` (→ platform), `Online`/`LastSeen` (→ reachability),
- * `Relay` vs `CurAddr` (→ direct-vs-relayed latency hint), `DNSName`, and
- * `TailscaleIPs`. `parseTailscaleStatus` turns that JSON into draft device
- * profiles so `agents devices sync` can self-populate instead of you
- * hand-entering hosts. Kept a pure function (JSON in, profiles out) so it is
- * unit-testable without a live tailnet.
- */
 import { spawnSync } from 'child_process';
 import { platformFromOs, } from './registry.js';
-/** Strip MagicDNS's trailing dot so the name is usable as an ssh HostName. */
 function trimDnsDot(dns) {
     if (!dns)
         return undefined;
     return dns.endsWith('.') ? dns.slice(0, -1) : dns;
 }
-/** First IPv4 in the node's address list (preferred over IPv6 for ssh). */
 function firstIpv4(ips) {
     if (!ips)
         return undefined;
     return ips.find((ip) => /^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) ?? ips[0];
 }
-/**
- * Slugify a raw Tailscale HostName into a valid logical device name (ssh alias
- * charset). Used only as a fallback — when a node has a DNSName we prefer its
- * first label, which is the canonical slug Tailscale itself derived.
- */
 export function slugifyHostName(hostName) {
     return hostName
         .toLowerCase()
-        .replace(/['’"]/g, '') // drop quotes/apostrophes (so "Bisma's" → "bismas", matching MagicDNS)
+        .replace(/['’"]/g, '')
         .replace(/[^a-z0-9._-]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
-/**
- * The logical name for a node. macOS computer names contain spaces and
- * apostrophes ("Bisma's MacBook Pro") and iOS devices all report HostName
- * "localhost" — both break as ssh aliases and the latter collides in the
- * registry. The MagicDNS label (first segment of DNSName) is already a unique,
- * valid slug per device, so prefer it; fall back to a slugified HostName.
- */
 function deviceNameFor(raw, dnsName) {
     const label = dnsName?.split('.')[0];
     if (label && label.length > 0)
@@ -57,8 +32,6 @@ function toNode(raw) {
     const name = deviceNameFor(raw, dnsName);
     if (!name)
         return null;
-    // A non-empty CurAddr means the last handshake was a direct connection;
-    // an empty CurAddr with a Relay means traffic is going through DERP.
     const direct = Boolean(raw.CurAddr && raw.CurAddr.length > 0);
     return {
         name,
@@ -72,11 +45,6 @@ function toNode(raw) {
         sharee: Boolean(raw.ShareeNode),
     };
 }
-/**
- * Parse `tailscale status --json` output into one node per tailnet device,
- * including Self. Throws on malformed JSON. Nodes without a HostName are
- * skipped (they cannot be addressed by a logical name).
- */
 export function parseTailscaleStatus(json) {
     let parsed;
     try {
@@ -98,7 +66,6 @@ export function parseTailscaleStatus(json) {
     }
     return out;
 }
-/** Turn a parsed Tailscale node into the registry fields it can populate. */
 export function nodeToDeviceInput(node) {
     return {
         platform: node.platform,
@@ -111,10 +78,6 @@ export function nodeToDeviceInput(node) {
         },
     };
 }
-/**
- * Run `tailscale status --json` and return its raw stdout. Throws a clear
- * error when the binary is missing or the daemon is not reachable.
- */
 export function tailscaleStatusJson() {
     const res = spawnSync('tailscale', ['status', '--json'], { encoding: 'utf-8', windowsHide: true });
     if (res.error && res.error.code === 'ENOENT') {

package/dist/lib/devices/terminfo.d.ts

@@ -1,44 +1,17 @@
 import { type DeviceProfile } from './registry.js';
-/**
- * Decide whether an interactive login warrants a terminfo push. Pure so the
- * gating logic is unit-testable without touching ssh or the filesystem.
- *
- * @param interactive true only for a real login (no remote command) on a human tty.
- */
 export declare function shouldSyncTerminfo(params: {
     term?: string;
     shell: DeviceProfile['shell'];
     interactive: boolean;
 }): boolean;
-/**
- * Cache key for a device: the remote **user@host**, not just the host. terminfo
- * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
- * are distinct sync targets — keying on host alone would let the first user's
- * stamp suppress the second user's (never-installed) sync. Mirrors
- * {@link sshTargetFor}'s user handling; falls back to the device name when the
- * address is unresolved.
- */
 export declare function terminfoHostKey(device: Pick<DeviceProfile, 'user' | 'name'>, addr: string | undefined): string;
-/** True when a fresh successful-sync stamp exists for this host+TERM. */
 export declare function terminfoSynced(host: string, term: string, cacheRoot?: string): boolean;
-/** Record a successful sync so repeat logins skip the push. Best-effort. */
 export declare function markTerminfoSynced(host: string, term: string, cacheRoot?: string): void;
-/** Export the local terminfo source for a TERM, or null if it can't be produced. */
 export declare function localTerminfoSource(term: string): string | null;
-/**
- * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
- * before an interactive login. Never throws; returns whether a push succeeded
- * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
- * SAME host-key + auth options the real login uses, minus the interactive tty —
- * so a password-auth device resolves through the askpass shim without a second
- * human prompt.
- */
 export declare function syncTerminfoToDevice(opts: {
     device: DeviceProfile;
     host: string;
     term: string | undefined;
-    /** ssh argv for a non-interactive `tic -x -` exec against this device. */
     sshArgs: string[];
-    /** Env overlay for that ssh (askpass wiring for password devices). */
     sshEnv: Record<string, string>;
 }): boolean;