@huaqiu/dsh-eda-host 0.6.9 → 0.6.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.mts CHANGED
@@ -22,6 +22,13 @@ interface EdaHostConfig {
22
22
  pcbBoardPathPrefix?: string;
23
23
  /** Path prefix for host discovery; default "/api/v1/host". */
24
24
  hostPathPrefix?: string;
25
+ /**
26
+ * Path prefix for the schematic→PCB sync command; default
27
+ * "/api/v1/sync-schematic-to-pcb". The plugin POSTs the existing
28
+ * `sync_sch_to_pcb` command (hq.runtime.v1.Command field 42) to this route;
29
+ * hq-edge forwards it to the EDA host's native handler.
30
+ */
31
+ syncSchematicToPcbPathPrefix?: string;
25
32
  /**
26
33
  * End-to-end budget for one EDA-host request, in milliseconds.
27
34
  *
@@ -308,6 +315,14 @@ interface EdaHostClient {
308
315
  * resolves to an all-empty `PcbSnapshot` — never an error.
309
316
  */
310
317
  getPcbBoard(options?: EdaHostRequestOptions): Promise<PcbSnapshot>;
318
+ /**
319
+ * Request the connected EDA host to synchronize the current schematic with
320
+ * the PCB (the existing `hq.runtime.v1.Command.sync_sch_to_pcb`, field 42).
321
+ * Resolves when hq-edge reports the host executed the command successfully;
322
+ * throws a `NetlistError` on any failure (transport, timeout, host-reported,
323
+ * or unsupported). It performs no synchronization itself.
324
+ */
325
+ syncSchematicToPcb(options?: EdaHostRequestOptions): Promise<void>;
311
326
  }
312
327
  /**
313
328
  * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
package/lib/index.mjs CHANGED
@@ -12,6 +12,7 @@ function resolveEdaHostConfig(config, env = process.env) {
12
12
  const pcbSelectionPrefix = config?.pcbSelectionPathPrefix ?? env.HQ_EDGE_PCB_SELECTION_PATH ?? "/api/v1/pcb-selection";
13
13
  const pcbBoardPrefix = config?.pcbBoardPathPrefix ?? env.HQ_EDGE_PCB_BOARD_PATH ?? "/api/v1/pcb-board";
14
14
  const hostPrefix = config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? "/api/v1/host";
15
+ const syncSchematicToPcbPrefix = config?.syncSchematicToPcbPathPrefix ?? env.HQ_EDGE_SYNC_SCHEMATIC_TO_PCB_PATH ?? "/api/v1/sync-schematic-to-pcb";
15
16
  const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS;
16
17
  const timeout = Number.parseInt(String(timeoutRaw ?? ""), 10);
17
18
  return {
@@ -20,6 +21,7 @@ function resolveEdaHostConfig(config, env = process.env) {
20
21
  pcbSelectionPathPrefix: pcbSelectionPrefix,
21
22
  pcbBoardPathPrefix: pcbBoardPrefix,
22
23
  hostPathPrefix: hostPrefix,
24
+ syncSchematicToPcbPathPrefix: syncSchematicToPcbPrefix,
23
25
  requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
24
26
  };
25
27
  }
@@ -47,6 +49,10 @@ const HOST_ROUTE = {
47
49
  function hostUrlOf(config, route) {
48
50
  return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.hostPathPrefix ?? "/api/v1/host").replace(/^\/+|\/+$/g, "")}${HOST_ROUTE[route]}`;
49
51
  }
52
+ /** Build the absolute URL for the schematic→PCB sync command route. */
53
+ function syncSchematicToPcbUrlOf(config) {
54
+ return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.syncSchematicToPcbPathPrefix ?? "/api/v1/sync-schematic-to-pcb").replace(/^\/+|\/+$/g, "")}`;
55
+ }
50
56
  //#endregion
51
57
  //#region src/types.ts
52
58
  var NetlistError = class extends Error {
@@ -194,6 +200,33 @@ function createEdaHostClient(config, deps = {}) {
194
200
  }
195
201
  return response.json();
196
202
  }
203
+ /** Perform one POST and map failures, resolving only on a 2xx response. */
204
+ async function postSync(url, options, what) {
205
+ const signal = resolveSignal(config.requestTimeoutMs ?? 3e4, options?.signal);
206
+ let response;
207
+ try {
208
+ response = await fetchImpl(url, {
209
+ method: "POST",
210
+ headers: {
211
+ "content-type": "application/json",
212
+ Accept: "application/json"
213
+ },
214
+ body: "{}",
215
+ ...signal ? { signal } : {}
216
+ });
217
+ } catch (err) {
218
+ if (isAbortError(err)) throw new NetlistError("DEADLINE_EXCEEDED", `eda-host: ${what} request exceeded its time budget at ${url}`);
219
+ throw new NetlistError("UNAVAILABLE", `eda-host: cannot reach hq-edge at ${url}: ${String(err?.message ?? err)}`);
220
+ }
221
+ if (!response.ok) {
222
+ let detail = "";
223
+ try {
224
+ const body = await response.json();
225
+ if (typeof body.detail === "string") detail = body.detail;
226
+ } catch {}
227
+ throw new NetlistError(statusToKind(response.status), `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ""})`);
228
+ }
229
+ }
197
230
  async function fetchScope(scope, options) {
198
231
  return parseNetlistBody(await getJson(netlistUrlOf(resolveConfig(), scope), options, "netlist"));
199
232
  }
@@ -233,6 +266,9 @@ function createEdaHostClient(config, deps = {}) {
233
266
  },
234
267
  getPcbBoard: async (options) => {
235
268
  return parsePcbSnapshot(await getJson(pcbBoardUrlOf(resolveConfig()), options, "pcb board"), "PCB board");
269
+ },
270
+ syncSchematicToPcb: async (options) => {
271
+ await postSync(syncSchematicToPcbUrlOf(resolveConfig()), options, "schematic-to-pcb sync");
236
272
  }
237
273
  };
238
274
  }
@@ -252,6 +288,10 @@ function createEdaHostClient(config, deps = {}) {
252
288
  * get_eda_host_info which host, which version, where it is installed
253
289
  * get_eda_host_capabilities what the current host can actually do
254
290
  *
291
+ * One EDA host command (reuses the existing hq.runtime.v1 sync_sch_to_pcb):
292
+ *
293
+ * sync_schematic_to_pcb ask the host to synchronize schematic → PCB
294
+ *
255
295
  * The netlist tools are pure pass-throughs: they call the hq-edge netlist
256
296
  * router and return the semantic `SchematicNetlist` as lossless JSON. Errors
257
297
  * are propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
@@ -425,6 +465,27 @@ function createEdaHostTools(env) {
425
465
  });
426
466
  }
427
467
  }
468
+ }),
469
+ defineTool({
470
+ name: "sync_schematic_to_pcb",
471
+ description: "Request that the connected EDA host synchronize the current schematic with the PCB through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). This invokes the host's NATIVE schematic-to-PCB synchronization — the same operation as the host's \"Update PCB from Schematic\" action — by dispatching the existing hq.runtime.v1.Command.sync_sch_to_pcb command. It does NOT reimplement synchronization in TypeScript and requires no parameters. Returns { ok: true } when the host accepted and executed the synchronization command. A successful result confirms the host ran the command; it does NOT independently verify that every net and footprint is now identical — re-read the netlist (get_project_netlist) or board (get_pcb_board) afterward if you need to confirm the outcome. " + ERROR_SEMANTICS,
472
+ parameters: {},
473
+ output: {
474
+ schema: { type: "json" },
475
+ render: renderJson
476
+ },
477
+ async execute(_args, exec) {
478
+ try {
479
+ const options = exec?.signal ? { signal: exec.signal } : {};
480
+ await env.client.syncSchematicToPcb(options);
481
+ return asJson({ ok: true });
482
+ } catch (err) {
483
+ return asJson({
484
+ ok: false,
485
+ error: failureOf(err)
486
+ });
487
+ }
488
+ }
428
489
  })
429
490
  ];
430
491
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@huaqiu/dsh-eda-host",
3
- "version": "0.6.9",
3
+ "version": "0.6.11",
4
4
  "type": "module",
5
5
  "main": "./lib/index.mjs",
6
6
  "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
22
22
  "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
23
23
  },
24
24
  "dependencies": {
25
- "@huaqiu/dsh-plugin-log": "0.6.9"
25
+ "@huaqiu/dsh-plugin-log": "0.6.11"
26
26
  },
27
27
  "files": [
28
28
  "lib",
package/src/client.ts CHANGED
@@ -10,7 +10,7 @@
10
10
  * @module
11
11
  */
12
12
 
13
- import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbBoardUrlOf, pcbSelectionUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
13
+ import { DEFAULT_REQUEST_TIMEOUT_MS, hostUrlOf, netlistUrlOf, pcbBoardUrlOf, pcbSelectionUrlOf, syncSchematicToPcbUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
14
14
  import {
15
15
  NetlistError,
16
16
  type EdaHostCapability,
@@ -64,6 +64,14 @@ export interface EdaHostClient {
64
64
  * resolves to an all-empty `PcbSnapshot` — never an error.
65
65
  */
66
66
  getPcbBoard(options?: EdaHostRequestOptions): Promise<PcbSnapshot>
67
+ /**
68
+ * Request the connected EDA host to synchronize the current schematic with
69
+ * the PCB (the existing `hq.runtime.v1.Command.sync_sch_to_pcb`, field 42).
70
+ * Resolves when hq-edge reports the host executed the command successfully;
71
+ * throws a `NetlistError` on any failure (transport, timeout, host-reported,
72
+ * or unsupported). It performs no synchronization itself.
73
+ */
74
+ syncSchematicToPcb(options?: EdaHostRequestOptions): Promise<void>
67
75
  }
68
76
 
69
77
  /** HTTP status → semantic error kind (see routes/edaHostStatus.ts on hq-edge). */
@@ -264,6 +272,52 @@ export function createEdaHostClient(
264
272
  return response.json()
265
273
  }
266
274
 
275
+ /** Perform one POST and map failures, resolving only on a 2xx response. */
276
+ async function postSync(
277
+ url: string,
278
+ options: EdaHostRequestOptions | undefined,
279
+ what: string,
280
+ ): Promise<void> {
281
+ const signal = resolveSignal(config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, options?.signal)
282
+
283
+ let response: Response
284
+ try {
285
+ response = await fetchImpl(url, {
286
+ method: 'POST',
287
+ headers: { 'content-type': 'application/json', Accept: 'application/json' },
288
+ body: '{}',
289
+ ...(signal ? { signal } : {}),
290
+ })
291
+ } catch (err) {
292
+ // An aborted request is a timeout, never an empty result.
293
+ if (isAbortError(err)) {
294
+ throw new NetlistError(
295
+ 'DEADLINE_EXCEEDED',
296
+ `eda-host: ${what} request exceeded its time budget at ${url}`,
297
+ )
298
+ }
299
+ // Connection-level failure: host not running / unreachable.
300
+ throw new NetlistError(
301
+ 'UNAVAILABLE',
302
+ `eda-host: cannot reach hq-edge at ${url}: ${String((err as Error)?.message ?? err)}`,
303
+ )
304
+ }
305
+
306
+ if (!response.ok) {
307
+ let detail = ''
308
+ try {
309
+ const body = (await response.json()) as { detail?: unknown }
310
+ if (typeof body.detail === 'string') detail = body.detail
311
+ } catch {
312
+ // non-JSON error body — fall through with empty detail
313
+ }
314
+ throw new NetlistError(
315
+ statusToKind(response.status),
316
+ `eda-host: ${what} request failed (${response.status}${detail ? `: ${detail}` : ''})`,
317
+ )
318
+ }
319
+ }
320
+
267
321
  async function fetchScope(
268
322
  scope: NetlistScope,
269
323
  options?: EdaHostRequestOptions,
@@ -346,5 +400,11 @@ export function createEdaHostClient(
346
400
  const body = (await getJson(url, options, 'pcb board')) as unknown
347
401
  return parsePcbSnapshot(body, 'PCB board')
348
402
  },
403
+
404
+ syncSchematicToPcb: async (options) => {
405
+ const resolved = resolveConfig()
406
+ const url = syncSchematicToPcbUrlOf(resolved)
407
+ await postSync(url, options, 'schematic-to-pcb sync')
408
+ },
349
409
  }
350
410
  }
package/src/config.ts CHANGED
@@ -21,6 +21,13 @@ export interface EdaHostConfig {
21
21
  pcbBoardPathPrefix?: string
22
22
  /** Path prefix for host discovery; default "/api/v1/host". */
23
23
  hostPathPrefix?: string
24
+ /**
25
+ * Path prefix for the schematic→PCB sync command; default
26
+ * "/api/v1/sync-schematic-to-pcb". The plugin POSTs the existing
27
+ * `sync_sch_to_pcb` command (hq.runtime.v1.Command field 42) to this route;
28
+ * hq-edge forwards it to the EDA host's native handler.
29
+ */
30
+ syncSchematicToPcbPathPrefix?: string
24
31
  /**
25
32
  * End-to-end budget for one EDA-host request, in milliseconds.
26
33
  *
@@ -40,6 +47,8 @@ export const DEFAULT_PCB_BOARD_PATH_PREFIX = '/api/v1/pcb-board'
40
47
 
41
48
  export const DEFAULT_HOST_PATH_PREFIX = '/api/v1/host'
42
49
 
50
+ export const DEFAULT_SYNC_SCHEMATIC_TO_PCB_PATH_PREFIX = '/api/v1/sync-schematic-to-pcb'
51
+
43
52
  export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
44
53
 
45
54
  /** Scope → route suffix on the host netlist router. */
@@ -68,6 +77,10 @@ export function resolveEdaHostConfig(
68
77
  DEFAULT_PCB_BOARD_PATH_PREFIX
69
78
  const hostPrefix =
70
79
  config?.hostPathPrefix ?? env.HQ_EDGE_HOST_PATH ?? DEFAULT_HOST_PATH_PREFIX
80
+ const syncSchematicToPcbPrefix =
81
+ config?.syncSchematicToPcbPathPrefix ??
82
+ env.HQ_EDGE_SYNC_SCHEMATIC_TO_PCB_PATH ??
83
+ DEFAULT_SYNC_SCHEMATIC_TO_PCB_PATH_PREFIX
71
84
  const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS
72
85
  const timeout = Number.parseInt(String(timeoutRaw ?? ''), 10)
73
86
  return {
@@ -76,6 +89,7 @@ export function resolveEdaHostConfig(
76
89
  pcbSelectionPathPrefix: pcbSelectionPrefix,
77
90
  pcbBoardPathPrefix: pcbBoardPrefix,
78
91
  hostPathPrefix: hostPrefix,
92
+ syncSchematicToPcbPathPrefix: syncSchematicToPcbPrefix,
79
93
  requestTimeoutMs:
80
94
  Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
81
95
  }
@@ -127,3 +141,13 @@ export function hostUrlOf(config: EdaHostConfig, route: HostRoute): string {
127
141
  const prefix = (config.hostPathPrefix ?? DEFAULT_HOST_PATH_PREFIX).replace(/^\/+|\/+$/g, '')
128
142
  return `${base}/${prefix}${HOST_ROUTE[route]}`
129
143
  }
144
+
145
+ /** Build the absolute URL for the schematic→PCB sync command route. */
146
+ export function syncSchematicToPcbUrlOf(config: EdaHostConfig): string {
147
+ const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
148
+ const prefix = (config.syncSchematicToPcbPathPrefix ?? DEFAULT_SYNC_SCHEMATIC_TO_PCB_PATH_PREFIX).replace(
149
+ /^\/+|\/+$/g,
150
+ '',
151
+ )
152
+ return `${base}/${prefix}`
153
+ }
package/src/index.ts CHANGED
@@ -2,14 +2,16 @@
2
2
  * `@huaqiu/dsh-eda-host` — node plugin entry.
3
3
  *
4
4
  * Provides the `edaHost` service (semantic EDA-host capability) and registers
5
- * six agent tools:
5
+ * eight agent tools:
6
6
  *
7
7
  * get_project_netlist complete project netlist
8
8
  * get_selection_netlist currently selected components netlist
9
9
  * get_active_page_netlist active schematic page netlist
10
10
  * get_pcb_selection semantic PCB selection of the current PCB editor
11
+ * get_pcb_board complete semantic PCB board snapshot
11
12
  * get_eda_host_info which EDA host, version, installation
12
13
  * get_eda_host_capabilities what the current host can actually do
14
+ * sync_schematic_to_pcb ask the host to synchronize schematic → PCB
13
15
  *
14
16
  * ── Architectural boundary (task: add-dsh-eda-host) ─────────────────────────
15
17
  * The ONLY production request path is DSH → dsh-eda-host → hq-edge → EDA host.
package/src/tools.ts CHANGED
@@ -12,6 +12,10 @@
12
12
  * get_eda_host_info which host, which version, where it is installed
13
13
  * get_eda_host_capabilities what the current host can actually do
14
14
  *
15
+ * One EDA host command (reuses the existing hq.runtime.v1 sync_sch_to_pcb):
16
+ *
17
+ * sync_schematic_to_pcb ask the host to synchronize schematic → PCB
18
+ *
15
19
  * The netlist tools are pure pass-throughs: they call the hq-edge netlist
16
20
  * router and return the semantic `SchematicNetlist` as lossless JSON. Errors
17
21
  * are propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
@@ -70,6 +74,10 @@ type PcbBoardResult =
70
74
  | { ok: true; snapshot: PcbSnapshot }
71
75
  | { ok: false; error: { kind: string; message: string } }
72
76
 
77
+ type SyncSchematicToPcbResult =
78
+ | { ok: true }
79
+ | { ok: false; error: { kind: string; message: string } }
80
+
73
81
  /**
74
82
  * Every failure kind, and what the agent should do about it.
75
83
  *
@@ -278,17 +286,47 @@ export function createNetListTools(env: NetlistToolEnv) {
278
286
  ERROR_SEMANTICS,
279
287
  parameters: {},
280
288
  output: { schema: { type: 'json' }, render: renderJson },
281
- async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
282
- try {
283
- const options: EdaHostRequestOptions = exec?.signal
284
- ? { signal: exec.signal }
285
- : {}
286
- const capabilities = await env.client.getEdaHostCapabilities(options)
287
- return asJson<HostCapabilitiesResult>({ ok: true, capabilities })
288
- } catch (err) {
289
- return asJson<HostCapabilitiesResult>({ ok: false, error: failureOf(err) })
290
- }
291
- },
292
- }),
289
+ async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
290
+ try {
291
+ const options: EdaHostRequestOptions = exec?.signal
292
+ ? { signal: exec.signal }
293
+ : {}
294
+ const capabilities = await env.client.getEdaHostCapabilities(options)
295
+ return asJson<HostCapabilitiesResult>({ ok: true, capabilities })
296
+ } catch (err) {
297
+ return asJson<HostCapabilitiesResult>({ ok: false, error: failureOf(err) })
298
+ }
299
+ },
300
+ }),
301
+
302
+ defineTool({
303
+ name: 'sync_schematic_to_pcb',
304
+ description:
305
+ `Request that the connected EDA host synchronize the current schematic ` +
306
+ `with the PCB through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). ` +
307
+ `This invokes the host's NATIVE schematic-to-PCB synchronization — the same ` +
308
+ `operation as the host's "Update PCB from Schematic" action — by dispatching the ` +
309
+ `existing hq.runtime.v1.Command.sync_sch_to_pcb command. It does NOT reimplement ` +
310
+ `synchronization in TypeScript and requires no parameters. ` +
311
+ `Returns { ok: true } when the host accepted and executed the synchronization ` +
312
+ `command. A successful result confirms the host ran the command; it does NOT ` +
313
+ `independently verify that every net and footprint is now identical — re-read the ` +
314
+ `netlist (get_project_netlist) or board (get_pcb_board) afterward if you need to ` +
315
+ `confirm the outcome. ` +
316
+ ERROR_SEMANTICS,
317
+ parameters: {},
318
+ output: { schema: { type: 'json' }, render: renderJson },
319
+ async execute(_args: unknown, exec: ToolExecLike): Promise<Json> {
320
+ try {
321
+ const options: EdaHostRequestOptions = exec?.signal
322
+ ? { signal: exec.signal }
323
+ : {}
324
+ await env.client.syncSchematicToPcb(options)
325
+ return asJson<SyncSchematicToPcbResult>({ ok: true })
326
+ } catch (err) {
327
+ return asJson<SyncSchematicToPcbResult>({ ok: false, error: failureOf(err) })
328
+ }
329
+ },
330
+ }),
293
331
  ]
294
332
  }