dsh-foreman-node 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,7 +1,21 @@
-# Changelog
+## 0.1.1 — 2026-11-07
 
-本包是 [`dsh-foreman`](https://www.npmjs.com/package/dsh-foreman) 的设备侧，单独发版，
-但**协议与 hub 版本绑定**：两侧协议版本不一致时，握手就拒绝并给出可读原因。
+### 修复：装上去就把整个 profile 弄成「异常」
+
+设备包一进 profile 的 `bundles`，它的 patch 就会插入 `dsh-foreman-node` 这一行，
+而这一行**还没有任何 config**——`0.1.0` 的 schema 把 `url` / `deviceId` / `token` 都写成 `.required()`，
+于是激活直接失败：
+
+```
+invalid config:
+  - $.url missing required value (at url)
+```
+
+整个 profile 因此显示为异常，而不是「这个设备还没配好」。
+
+现在这三项都有空字符串默认值，`apply` 在缺值时**干净地不激活**，只记一行说明缺哪几项、
+去哪儿填，profile 保持健康。值填齐后才开始拨号。
+只有空白的值也算缺——否则设备会一直拨一个空地址，看起来只是离线。
 
 ## 0.1.0 — 2026-11-07
 

package/lib/index.d.ts

@@ -186,11 +186,11 @@ interface NodeRoot {
 }
 /** 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. */
+  /** 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`. */
+  /** 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. */
+  /** 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[];
@@ -202,18 +202,34 @@ interface NodeConfig {
 /**
  * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
  *
+ * Everything is optional on purpose. A bundle patch inserts this row the moment the package is added to a profile,
+ * so `apply` runs before anyone has filled the values in — and a schema that demanded them would turn the whole
+ * profile red with "invalid config" on a fresh install. `apply` treats a blank address as "not configured yet":
+ * it says what is missing and stops, instead of dialling nowhere or refusing to activate.
+ *
  * 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.
  */
 declare const Config: 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.
+ */
+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 };
+export { Config, type Frame, type FrameAttachment, JobSessions, NodeClient, NodeConfig, NodeRoot, REPORT_STATES, type Root, VERSION, apply, foremanReportTool, inject, missingConfiguration, name };

package/lib/index.js

@@ -477,13 +477,18 @@ const VERSION = "0.1.0";
 /**
 * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
 *
+* Everything is optional on purpose. A bundle patch inserts this row the moment the package is added to a profile,
+* so `apply` runs before anyone has filled the values in — and a schema that demanded them would turn the whole
+* profile red with "invalid config" on a fresh install. `apply` treats a blank address as "not configured yet":
+* it says what is missing and stops, instead of dialling nowhere or refusing to activate.
+*
 * 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.
 */
 const Config = s.object({
-	url: s.string().required().description("The hub's address, such as wss://foreman.example.com. The device dials out to it."),
-	deviceId: s.string().required().description("This device's id, as registered on the hub with `Devices.add`."),
-	token: s.string().required().role("secret").description("This device's token; it is sent in the hello frame and nowhere else."),
+	url: s.string().default("").description("The hub's address, such as wss://foreman.example.com. The device dials out to it."),
+	deviceId: s.string().default("").description("This device's id, as registered on the hub with `Devices.add`."),
+	token: s.string().default("").role("secret").description("This device's token; it is sent in the hello frame and nowhere else."),
 	roots: s.array(s.object({
 		project: s.string().required(),
 		path: s.string().required()
@@ -491,6 +496,20 @@ const Config = s.object({
 	heartbeatMs: s.natural().default(15e3).description("How often to tell the hub this device is alive, in milliseconds."),
 	reconnectMs: s.natural().default(1e3).description("Delay before the first reconnect attempt, in milliseconds.")
 });
+/**
+* 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.
+*/
+function missingConfiguration(config) {
+	const missing = [];
+	if (config.url.trim() === "") missing.push("url");
+	if (config.deviceId.trim() === "") missing.push("deviceId");
+	if (config.token.trim() === "") missing.push("token");
+	if (missing.length === 0) return void 0;
+	return `dsh-foreman-node is not configured yet: ${missing.join(", ")} missing. Set them on the dsh-foreman-node row in the profile patch (the hub prints the token when you register the device).`;
+}
 const name = "dsh-foreman-node";
 /** DSH services a job needs; all are the host's own, and none is a foreman one. */
 const inject = [
@@ -504,10 +523,19 @@ const inject = [
 /**
 * 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.
 */
 async function apply(ctx, config) {
+	const missing = missingConfiguration(config);
+	if (missing !== void 0) {
+		ctx.logger.info("%s", missing);
+		return;
+	}
 	const jobs = new JobSessions(ctx);
 	const client = new NodeClient({
 		url: config.url,
@@ -570,4 +598,4 @@ async function receive(ctx, jobs, client, frame) {
 		});
 	}
 }
-export { Config, JobSessions, NodeClient, REPORT_STATES, VERSION, apply, foremanReportTool, inject, name };
+export { Config, JobSessions, NodeClient, REPORT_STATES, VERSION, apply, foremanReportTool, inject, missingConfiguration, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-foreman-node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Device side of dsh-foreman: connects out to a foreman hub, takes a job into a local DSH session, reports back. No ledger, no policy, no database.",
   "type": "module",
   "main": "lib/index.js",

package/src/index.ts

@@ -24,11 +24,11 @@ export interface NodeRoot { project: string; path: string }
 
 /** What the `dsh-foreman-node` entry in a profile's patch configures. */
 export interface NodeConfig {
-  /** The hub's stable address; the device dials out to it. */
+  /** 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`. */
+  /** 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. */
+  /** 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[]
@@ -41,19 +41,40 @@ export interface NodeConfig {
 /**
  * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
  *
+ * Everything is optional on purpose. A bundle patch inserts this row the moment the package is added to a profile,
+ * so `apply` runs before anyone has filled the values in — and a schema that demanded them would turn the whole
+ * profile red with "invalid config" on a fresh install. `apply` treats a blank address as "not configured yet":
+ * it says what is missing and stops, instead of dialling nowhere or refusing to activate.
+ *
  * 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.
  */
 export const Config: Schemastery<NodeConfig> = s.object({
-  url: s.string().required().description('The hub\'s address, such as wss://foreman.example.com. The device dials out to it.'),
-  deviceId: s.string().required().description('This device\'s id, as registered on the hub with `Devices.add`.'),
-  token: s.string().required().role('secret').description('This device\'s token; it is sent in the hello frame and nowhere else.'),
+  url: s.string().default('').description('The hub\'s address, such as wss://foreman.example.com. The device dials out to it.'),
+  deviceId: s.string().default('').description('This device\'s id, as registered on the hub with `Devices.add`.'),
+  token: s.string().default('').role('secret').description('This device\'s token; it is sent in the hello frame and nowhere else.'),
   roots: s.array(s.object({ project: s.string().required(), path: s.string().required() })).default([])
     .description('Projects this device can work on: a logical name and this machine\'s own absolute path, kept verbatim.'),
   heartbeatMs: s.natural().default(15_000).description('How often to tell the hub this device is alive, in milliseconds.'),
   reconnectMs: s.natural().default(1_000).description('Delay before the first reconnect attempt, in milliseconds.'),
 })
 
+/**
+ * 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.
+ */
+export function missingConfiguration(config: NodeConfig): string | undefined {
+  const missing: string[] = []
+  if (config.url.trim() === '') missing.push('url')
+  if (config.deviceId.trim() === '') missing.push('deviceId')
+  if (config.token.trim() === '') missing.push('token')
+  if (missing.length === 0) return undefined
+  return `dsh-foreman-node is not configured yet: ${missing.join(', ')} ` +
+    `missing. Set them on the dsh-foreman-node row in the profile patch (the hub prints the token when you register the device).`
+}
+
 export const name = 'dsh-foreman-node'
 /** DSH services a job needs; all are the host's own, and none is a foreman one. */
 export const inject = ['sessionController', 'sessionPersistence', 'workspaceRegistry', 'permissionPresets', 'tools', 'agents']
@@ -61,10 +82,19 @@ export const inject = ['sessionController', 'sessionPersistence', 'workspaceRegi
 /**
  * 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.
  */
 export async function apply(ctx: Context, config: NodeConfig): Promise<void> {
+  const missing = missingConfiguration(config)
+  if (missing !== undefined) {
+    ctx.logger.info('%s', missing)
+    return
+  }
   const jobs = new JobSessions(ctx)
   const client = new NodeClient({
     url: config.url,