dsh-foreman-node 0.1.0 → 0.2.0

package/lib/index.d.ts

@@ -1,6 +1,62 @@
 import { Frame, FrameAttachment, FrameDedupe, Root } from "./protocol.js";
-import { Context } from "@deepseek-ai/cordis";
+import { Context, Volatile } from "@deepseek-ai/cordis";
+import { IncomingMessage, ServerResponse } from "node:http";
 import { Agent } from "@deepseek-ai/dsh-agent";
+/**
+ * The device's configuration shape, with no Node imports.
+ *
+ * This module exists so the browser page and the Node plugin can share one definition. The page must not import
+ * `index.ts`: that file pulls in `node:net`, `node:child_process` and the job-session code, and a browser bundle that
+ * reaches them fails to load at boot — which is exactly how the first 0.2.0 build broke.
+ */
+/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
+interface NodeRoot {
+  project: string;
+  path: string;
+}
+/**
+ * How the device reaches a hub it cannot reach directly.
+ *
+ * The hub listens on loopback only — a deliberate constraint, because the ledger is the one thing worth protecting —
+ * so a device on another machine reaches it through a tunnel. With `enabled` the device opens that tunnel itself and
+ * dials its own end of it; `url` is then unused, not overridden, so switching back to a direct address restores it.
+ */
+interface SshConfig {
+  /** Open a tunnel to the hub instead of dialling `url` directly. */
+  enabled: boolean;
+  /** The hub machine: an address or a `~/.ssh/config` alias. */
+  host: string;
+  /** The hub machine's SSH port. */
+  port: number;
+  /** The SSH user on the hub machine. */
+  user: string;
+  /** The private key this device authenticates with. The configuration page lists these from `~/.ssh`. */
+  keyPath: string;
+  /** The port the hub listens on, on the hub machine. */
+  remotePort: number;
+  /** The local port the tunnel listens on; the device dials this. */
+  localPort: number;
+}
+/** What the `dsh-foreman-node` entry in a profile's patch configures. */
+interface NodeConfig {
+  /** The hub's stable address; the device dials out to it. Blank until someone fills it in. */
+  url: string;
+  /** This device's id, as registered on the hub with `Devices.add`. Blank until someone fills it in. */
+  deviceId: string;
+  /** This device's token; sent in the hello and nowhere else. Blank until someone fills it in. */
+  token: string;
+  /** The projects this device can work on. */
+  roots: NodeRoot[];
+  /** How often to tell the hub this device is alive, in milliseconds. */
+  heartbeatMs: number;
+  /** Delay before the first reconnect attempt, in milliseconds. */
+  reconnectMs: number;
+  /** How to reach a hub that is not directly reachable. */
+  ssh: SshConfig;
+}
+/** The SSH defaults, spread over whatever the host hands in, so a partial block is still complete. */
+declare const SSH_DEFAULTS: SshConfig;
+declare function configured(config: object | undefined): NodeConfig;
 /** What a socket has to offer; the global `WebSocket` satisfies it, and tests supply an object that does too. */
 interface SocketLike {
   readyState: number;
@@ -77,6 +133,146 @@ declare class NodeClient {
   accepted(assignmentId: string): void;
   private scheduleReconnect;
 }
+/** Where the tunnel is, in the only terms a person needs: not yet, trying, working, broken. */
+type TunnelState = 'idle' | 'connecting' | 'connected' | 'failed';
+/** The minimum of a spawned process this class uses, so a test never starts a real ssh. */
+interface TunnelChild {
+  killed: boolean;
+  kill(signal?: NodeJS.Signals): boolean;
+  on(event: 'exit', listener: (code: number | null) => void): unknown;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  stderr?: {
+    on(event: 'data', listener: (chunk: Buffer) => void): unknown;
+  } | null;
+}
+type SpawnTunnel = (argv: readonly string[]) => TunnelChild;
+/** Resolves whether something accepts a TCP connection on a local port. */
+type ProbePort = (port: number) => Promise<boolean>;
+interface TunnelInput {
+  ssh: SshConfig;
+  spawn?: SpawnTunnel;
+  probe?: ProbePort;
+  /** Called on every state change, so the page and the log see the same transitions the client acts on. */
+  onState?: (state: TunnelState, failure?: string) => void;
+  log?: (text: string) => void;
+  /** Delay before the first retry, in milliseconds; doubles each time up to `maxRetryMs`. */
+  retryMs?: number;
+  maxRetryMs?: number;
+}
+/** The argv of the forwarding process, in order, exactly as the tests pin it. */
+declare function tunnelArgs(ssh: SshConfig): string[];
+/**
+ * Keeps one forwarding process alive, reporting what it is doing.
+ *
+ * A retry is always a *new* process: an ssh that exited cannot be revived, and reusing the object would report a
+ * state no process is in. `stop()` is idempotent and leaves nothing behind, including a pending retry timer.
+ */
+declare class Tunnel {
+  private readonly input;
+  private current;
+  private lastFailure;
+  private child;
+  private timer;
+  /** The pending escalation from SIGTERM to SIGKILL after `stop()`. */
+  private killTimer;
+  /** Whether the local port was free when the current attempt spawned; only then can an answer be our own forward. */
+  private portWasFree;
+  /**
+   * The child that has actually exited, if any.
+   *
+   * `ChildProcess.killed` means "a signal was sent", not "the process is gone", so it cannot answer "is it still
+   * running" — and using it that way makes the SIGKILL escalation unreachable. The exit event is the only truth.
+   */
+  private exitedChild;
+  /** A generation counter, so a late callback from a superseded attempt cannot overwrite the current state. */
+  private generation;
+  private retryMs;
+  private readonly maxRetryMs;
+  private readonly spawn;
+  private readonly probe;
+  constructor(input: TunnelInput);
+  state(): TunnelState;
+  /** Why the last attempt failed, already rewritten into something a person can act on. */
+  failure(): string | undefined;
+  /** Start the first attempt, or do nothing if one is already running. */
+  start(): void;
+  /**
+   * End the process and any pending retry; safe to call more than once.
+   *
+   * SIGTERM first, then SIGKILL: an ssh that ignores or is slow to handle the polite signal would otherwise outlive
+   * the plugin, keep `localPort` bound, and make the next activation's first attempt fail on a port it still owns.
+   */
+  stop(): void;
+  /** One attempt: check the port is free, spawn, wait for the local port, then either stay connected or fail. */
+  private attempt;
+  /**
+   * Poll the local port until it answers or the attempt is superseded; a first answer means the forward works.
+   *
+   * Reaching `connected` deliberately does NOT mark the attempt settled. The process is still running, and it is
+   * exactly the exit that follows a working tunnel — a dropped link, a restarted hub — that has to reach `fail` and
+   * schedule a retry. Marking it settled here would leave a device that connects once and then silently stops
+   * taking work, which is the hardest failure to notice.
+   */
+  private waitReady;
+  /** Record a failure, release the process, and schedule the next attempt with a growing delay. */
+  private fail;
+  private set;
+}
+/** One key a person may choose: never its contents, only what tells it apart from the others. */
+interface SshKey {
+  /** The filename, such as `id_ed25519`. */
+  name: string;
+  /** Its absolute path, which is what the configuration stores. */
+  path: string;
+  /** The trailing comment of the public half, usually `user@machine`; empty when it has none. */
+  comment: string;
+}
+/**
+ * Lists the usable private keys in a directory.
+ *
+ * A key counts as usable only when its public half is beside it: that is how `ssh-keygen` writes them, and a private
+ * key without one is either half-deleted or was never finished, so offering it would only fail later at the tunnel.
+ * Anything unreadable is skipped rather than thrown, because a permissions problem on one file must not empty the list.
+ */
+declare function listKeys(directory: string): SshKey[];
+/** Runs one command and reports its exit status with its output; injectable so a test never starts ssh. */
+type RunCommand = (argv: readonly string[]) => Promise<{
+  code: number | null;
+  output: string;
+}>;
+/** The connection the page is testing, exactly the four fields it collects. */
+interface TestInput {
+  host: string;
+  port: number;
+  user: string;
+  keyPath: string;
+}
+/**
+ * The argv of an authentication test.
+ *
+ * It asks for a command that does nothing (`true`) rather than opening a forward, because the question is only
+ * "does this key authenticate", and `BatchMode=yes` keeps it from stopping to ask for a passphrase nobody can type.
+ */
+declare function testArgs({ host, port, user, keyPath }: TestInput): string[];
+interface RouteHost {
+  /** The web server service: the only thing this module needs from the host. */
+  register(route: {
+    kind: 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+  }): () => void;
+  /** The port the web server listens on, used by the same-origin check. */
+  port: number;
+  /** The scheme the web server serves, so a TLS-terminated host's `https://` origin is accepted. */
+  protocol?: string;
+}
+/**
+ * Registers the routes and returns their disposer.
+ *
+ * `listKeys` and `run` are injectable so tests can answer without a filesystem or a child process; production passes
+ * a directory and the real runner.
+ */
+declare function registerNodeRoutes(host: RouteHost, directory: string, run?: RunCommand): () => void;
 /**
  * The `foreman_report` tool a device registers on a job Session.
  *
@@ -178,42 +374,63 @@ declare class JobSessions {
   reportTools(agent: Agent, assignmentId: string, onReport: (assignmentId: string, report: DeviceReport) => void): void;
 }
 /** Version reported in the hello, so the hub can tell which device build is talking. */
-declare const VERSION = "0.1.0";
-/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
-interface NodeRoot {
-  project: string;
-  path: string;
-}
-/** What the `dsh-foreman-node` entry in a profile's patch configures. */
-interface NodeConfig {
-  /** The hub's stable address; the device dials out to it. */
-  url: string;
-  /** This device's id, as registered on the hub with `Devices.add`. */
-  deviceId: string;
-  /** This device's token; sent in the hello and nowhere else. */
-  token: string;
-  /** The projects this device can work on. */
-  roots: NodeRoot[];
-  /** How often to tell the hub this device is alive, in milliseconds. */
-  heartbeatMs: number;
-  /** Delay before the first reconnect attempt, in milliseconds. */
-  reconnectMs: number;
-}
+declare const VERSION = "0.2.0";
+/**
+ * Why every field is volatile.
+ *
+ * Not for hot reload: it is the switch that makes the entry visible to DSH's settings system at all. `dsh-settings`
+ * skips every plugin entry whose `volatileForm(schema)` is undefined, and that only finds fields reachable through a
+ * volatile ancestor. Without it the configuration page has no form to render and sits on "reading configuration"
+ * forever — no fields, no test button, no save.
+ *
+ * A volatile field arrives wrapped, so its value is read with `.get()`; `configured()` is what unwraps a whole
+ * `NodeConfig` for the code that would rather not know. Marking the object instead of each field is not an option:
+ * `.volatile()` on the object replaces every default with `{}`, so `Config({})` loses all of them.
+ */
+/**
+ * What `apply` actually receives: every field wrapped, since each one is volatile.
+ *
+ * Declared as an alias rather than inferred so the plugin's public signature does not name a `schemastery` symbol the
+ * emitted declaration cannot reference portably.
+ */
+type ConfigInput = { [K in keyof NodeConfig]: NodeConfig[K] | Volatile<NodeConfig[K]>; };
 /**
- * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
+ * The schema, asserted rather than annotated.
  *
- * The annotation names the schema type through the global `Schemastery` namespace rather than letting it be inferred:
- * an inferred type here names a `cosmokit` symbol the emitted declaration cannot reference portably.
+ * An annotation makes the declaration portable but cannot express what a volatile field does to a field's type, so the
+ * mismatch moves into the annotation. The assertion keeps the published `.d.ts` free of `schemastery` internals and
+ * puts the shape in one place; `configured()` is what re-establishes the real types at every read.
  */
-declare const Config: Schemastery<NodeConfig>;
+declare const Typed: Schemastery<NodeConfig>;
+/**
+ * What this configuration still needs before the device can dial its hub, or undefined when it is complete.
+ *
+ * A missing value is reported by name so an operator can fill it in without reading the source; a value that is only
+ * whitespace counts as missing, because a device that dials a blank address retries forever and looks merely offline.
+ */
+/**
+ * The address this device dials.
+ *
+ * With the tunnel on, that is the local end of it: `url` names the hub at its own address, which the tunnel exists to
+ * make reachable, so dialling `url` would bypass the tunnel entirely and look like an offline device. Keeping the two
+ * cases in one function is what stops `apply` from picking the wrong one.
+ */
+declare function hubUrlOf(config: NodeConfig): string;
+declare function missingConfiguration(config: NodeConfig): string | undefined;
 declare const name = "dsh-foreman-node";
 /** DSH services a job needs; all are the host's own, and none is a foreman one. */
 declare const inject: string[];
 /**
  * Start the device.
  *
+ * A package that has just been installed has its row in the profile patch with no values in it yet. Activating
+ * cleanly and saying what is still missing keeps the whole profile healthy; throwing here is what made a fresh
+ * install report the profile as broken.
+ *
  * The plugin returns once the connection is attempted, not once it succeeds: a device must boot and stay usable
  * while its hub is unreachable, and the client keeps retrying in the background.
  */
-declare function apply(ctx: Context, config: NodeConfig): Promise<void>;
-export { Config, type Frame, type FrameAttachment, JobSessions, NodeClient, NodeConfig, NodeRoot, REPORT_STATES, type Root, VERSION, apply, foremanReportTool, inject, name };
+declare function apply(ctx: Context, raw: ConfigInput): Promise<void>;
+/** The directory the key list reads; `~/.ssh` on a machine where the current user is the one configuring it. */
+declare function sshDirectory(): string;
+export { Typed as Config, ConfigInput, type Frame, type FrameAttachment, JobSessions, NodeClient, type NodeConfig, type NodeRoot, REPORT_STATES, type Root, SSH_DEFAULTS, type SshConfig, Tunnel, VERSION, apply, configured, foremanReportTool, hubUrlOf, inject, listKeys, missingConfiguration, name, registerNodeRoutes, sshDirectory, testArgs, tunnelArgs };