@huaqiu/dsh-eda-host 0.3.20 → 0.3.22

package/cordis.patch.yml

@@ -1,8 +1,11 @@
 # DSH bundle patch: inserts the Huaqiu EDA host netlist tool plugin.
-# The entry inject must match the node-half module contract (`src/index.ts` —
-# export const inject). The tool's apply() reads the `tools` service; the
-# hq-edge supervisor delivers the base URL as overlay config.
+# The entry `inject` MUST match the node-half module contract (`src/index.ts`
+# `export const inject`): `hqEdge` + `tools`. `hqEdge` is REQUIRED — the
+# edge-bridge (HOST) provides it and its `baseUrl` is the loopback HQ Edge
+# endpoint the netlist tools fetch from (`createNodeHqEdge(upstreamRoot,…)` →
+# `get baseUrl()`). Omitting `hqEdge` from inject makes `apply()`'s
+# `ctx.hqEdge` access throw `cannot get property "hqEdge" without inject`.
 - insert:
     - id: huaqiu-dsh-eda-host
       name: '@huaqiu/dsh-eda-host'
-      inject: ['tools']
+      inject: ['hqEdge', 'tools']

package/lib/index.d.mts

@@ -89,20 +89,58 @@ interface EdaHostClient {
 //#region src/index.d.ts
 /** Plugin id — matches package.json. */
 declare const name = "@huaqiu/dsh-eda-host";
-/** Cordis services this half depends on. */
-declare const inject: readonly ["tools"];
+/**
+ * Cordis services this half depends on.
+ *
+ * `hqEdge` is REQUIRED: the edge-bridge (the HOST) provides the node-side
+ * `hqEdge` service whose `baseUrl` is the loopback HQ Edge endpoint
+ * (`createNodeHqEdge(upstreamRoot, …)` → `get baseUrl()`). Without it the
+ * plugin cannot reach hq-edge at all — by design it cannot work standalone
+ * (the user-confirmed contract is "eda-host cannot work without hqEdge").
+ * Declaring it here is what lets `apply()` read `ctx.hqEdge` without Cordis
+ * throwing `cannot get property "hqEdge" without inject` (its context proxy
+ * walks the fiber tree and throws at the root fiber when the service was
+ * never injected into this plugin's fiber).
+ *
+ * `tools` is the DSH node runtime tool registry used to register the netlist
+ * tools.
+ */
+declare const inject: readonly ["hqEdge", "tools"];
 declare module '@deepseek-ai/cordis' {
   interface Context {
     edaHost: EdaHostClient;
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is the
+     * loopback HQ Edge endpoint, e.g. "http://localhost:18080". We read it
+     * lazily so this plugin does not hard-depend on the bridge and still works
+     * in standalone DSH installs (where the service is absent).
+     */
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is the
+     * loopback HQ Edge endpoint, e.g. "http://localhost:18080". This is a
+     * REQUIRED inject (see `export const inject` above): `apply()` reads
+     * `ctx.hqEdge` to resolve the endpoint, so the service must be present or
+     * Cordis throws `cannot get property "hqEdge" without inject`. When present
+     * but its `baseUrl` is empty, the netlist tools degrade to a clear
+     * FAILED_PRECONDITION rather than throwing at load time.
+     */
+    hqEdge: {
+      baseUrl?: string;
+    };
   }
 }
 /**
  * Host plugin body — provide `edaHost` and register the three netlist tools.
  *
- * When no host base URL is configured, tools return ok:false with
- * error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
- * plugin can be installed in standalone DSH where hq-edge is absent, and the
- * tools degrade to a clear semantic message.
+ * The HQ Edge endpoint is resolved **lazily at request time** (see
+ * `getHqEdgeBaseUrl`): the edge-bridge plugin provides `ctx.hqEdge.baseUrl`,
+ * which wins over the static `config.hqEdgeBaseUrl` / `HQ_EDGE_BASE_URL` env
+ * fallback. This matches how `@huaqiu/dsh-artifacts` and `@huaqiu/dsh-tool-
+ * symbol-footprint` reach hq-edge, and means the URL is correct even when this
+ * plugin is applied before the bridge. When no host URL is available at call
+ * time, the tools degrade to a clear FAILED_PRECONDITION instead of throwing at
+ * load time — so the plugin still installs in standalone DSH where hq-edge is
+ * absent.
  *
  * @param ctx - real cordis context (node side).
  * @returns disposer — unregisters the tools on plugin dispose.

package/lib/index.mjs

@@ -51,7 +51,12 @@ function statusToKind(status) {
 function createEdaHostClient(config, deps = {}) {
 	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
 	async function fetchScope(scope) {
-		const url = netlistUrlOf(config, scope);
+		const baseUrl = deps.baseUrlResolver?.()?.trim() ?? config.hqEdgeBaseUrl?.trim() ?? "";
+		if (baseUrl.length === 0) throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
+		const url = netlistUrlOf({
+			...config,
+			hqEdgeBaseUrl: baseUrl
+		}, scope);
 		let response;
 		try {
 			response = await fetchImpl(url, {
@@ -159,16 +164,36 @@ function createNetListTools(env) {
 //#region src/index.ts
 /** Plugin id — matches package.json. */
 const name = "@huaqiu/dsh-eda-host";
-/** Cordis services this half depends on. */
-const inject = ["tools"];
+/**
+* Cordis services this half depends on.
+*
+* `hqEdge` is REQUIRED: the edge-bridge (the HOST) provides the node-side
+* `hqEdge` service whose `baseUrl` is the loopback HQ Edge endpoint
+* (`createNodeHqEdge(upstreamRoot, …)` → `get baseUrl()`). Without it the
+* plugin cannot reach hq-edge at all — by design it cannot work standalone
+* (the user-confirmed contract is "eda-host cannot work without hqEdge").
+* Declaring it here is what lets `apply()` read `ctx.hqEdge` without Cordis
+* throwing `cannot get property "hqEdge" without inject` (its context proxy
+* walks the fiber tree and throws at the root fiber when the service was
+* never injected into this plugin's fiber).
+*
+* `tools` is the DSH node runtime tool registry used to register the netlist
+* tools.
+*/
+const inject = ["hqEdge", "tools"];
 const log = getLogger("dsh-eda-host");
 /**
 * Host plugin body — provide `edaHost` and register the three netlist tools.
 *
-* When no host base URL is configured, tools return ok:false with
-* error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
-* plugin can be installed in standalone DSH where hq-edge is absent, and the
-* tools degrade to a clear semantic message.
+* The HQ Edge endpoint is resolved **lazily at request time** (see
+* `getHqEdgeBaseUrl`): the edge-bridge plugin provides `ctx.hqEdge.baseUrl`,
+* which wins over the static `config.hqEdgeBaseUrl` / `HQ_EDGE_BASE_URL` env
+* fallback. This matches how `@huaqiu/dsh-artifacts` and `@huaqiu/dsh-tool-
+* symbol-footprint` reach hq-edge, and means the URL is correct even when this
+* plugin is applied before the bridge. When no host URL is available at call
+* time, the tools degrade to a clear FAILED_PRECONDITION instead of throwing at
+* load time — so the plugin still installs in standalone DSH where hq-edge is
+* absent.
 *
 * @param ctx - real cordis context (node side).
 * @returns disposer — unregisters the tools on plugin dispose.
@@ -176,31 +201,23 @@ const log = getLogger("dsh-eda-host");
 function apply(ctx, config = {}) {
 	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-eda-host requires the DSH `tools` service (ctx.tools.register).");
 	const resolved = resolveEdaHostConfig(config);
+	const getHqEdgeBaseUrl = () => {
+		const hq = ctx.hqEdge;
+		return hq?.baseUrl && hq.baseUrl.trim().length > 0 ? hq.baseUrl : void 0;
+	};
 	log.info("applying dsh-eda-host node half", {
-		hasHost: hasHost(resolved),
-		hqEdgeBaseUrl: resolved.hqEdgeBaseUrl ?? null,
+		hasConfigHost: hasHost(resolved),
+		hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
 		netlistPathPrefix: resolved.netlistPathPrefix
 	});
-	let client;
-	if (hasHost(resolved)) client = createEdaHostClient(resolved);
-	else client = {
-		getProjectNetlist: async () => {
-			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
-		},
-		getSelectionNetlist: async () => {
-			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
-		},
-		getActivePageNetlist: async () => {
-			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
-		}
-	};
+	const client = createEdaHostClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl });
 	ctx.effect(() => ctx.provide("edaHost", client));
 	const tools = createNetListTools({ client });
 	const disposers = [];
 	for (const tool of tools) disposers.push(ctx.tools.register(tool));
 	log.info("dsh-eda-host node half ready", {
 		tools: 3,
-		hostMode: hasHost(resolved)
+		configHostMode: hasHost(resolved)
 	});
 	return () => {
 		for (const dispose of disposers) try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-eda-host",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,7 +22,7 @@
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.3.20"
+    "@huaqiu/dsh-plugin-log": "0.3.22"
   },
   "files": [
     "lib",

package/src/client.ts

@@ -17,6 +17,16 @@ import {
 
 export interface EdaHostClientDeps {
   fetchImpl?: typeof fetch
+  /**
+   * Optional late-bound resolver for the HQ Edge base URL. When supplied it is
+   * consulted on EVERY request and takes priority over the static `config`
+   * value. This lets the node half read the endpoint from the `ctx.hqEdge`
+   * service the edge-bridge plugin provides — the same pattern `@huaqiu/
+   * dsh-artifacts` and `@huaqiu/dsh-tool-symbol-footprint` use — so the URL is
+   * picked up even if this plugin is applied before the bridge, and stays
+   * correct in standalone installs where no host is present.
+   */
+  baseUrlResolver?: () => string | undefined
 }
 
 export interface EdaHostClient {
@@ -43,7 +53,20 @@ export function createEdaHostClient(
   const fetchImpl = deps.fetchImpl ?? globalThis.fetch
 
   async function fetchScope(scope: NetlistScope): Promise<SchematicNetlist> {
-    const url = netlistUrlOf(config, scope)
+    // Resolve the host endpoint per request. A resolver (ctx.hqEdge) wins over
+    // the static config/env value; if neither yields a URL we degrade to the
+    // same clear FAILED_PRECONDITION the standalone install path uses.
+    const baseUrl = deps.baseUrlResolver?.()?.trim()
+      ?? config.hqEdgeBaseUrl?.trim()
+      ?? ''
+    if (baseUrl.length === 0) {
+      throw new NetlistError(
+        'FAILED_PRECONDITION',
+        'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
+          'netlist tools require the hq-edge EDA host bridge.',
+      )
+    }
+    const url = netlistUrlOf({ ...config, hqEdgeBaseUrl: baseUrl }, scope)
 
     let response: Response
     try {

package/src/index.ts

@@ -13,9 +13,12 @@
  * This plugin owns DSH integration only: it translates tool calls into hq-edge
  * requests and returns the semantic `SchematicNetlist`. It contains no
  * KiCad-specific logic, no schematic parsing, and no host IPC. The plugin is
- * self-contained — no `@hqedge/*` dependency; the base URL is delivered by the
- * hq-edge supervisor as overlay config (`hqEdgeBaseUrl`), with
- * `HQ_EDGE_BASE_URL` as env fallback (same convention as `@huaqiu/dsh-auth`).
+ * self-contained — no `@hqedge/*` dependency. The base URL is resolved at
+ * request time in this order: (1) the `ctx.hqEdge.baseUrl` service provided by
+ * the edge-bridge HOST (the loopback HQ Edge endpoint), then (2) the
+ * supervisor's overlay config (`hqEdgeBaseUrl`), then (3) `HQ_EDGE_BASE_URL`
+ * env fallback (same convention as `@huaqiu/dsh-auth`). `hqEdge` is a REQUIRED
+ * inject — the plugin cannot reach hq-edge without the bridge.
  *
  * @module @huaqiu/dsh-eda-host
  */
@@ -24,13 +27,27 @@ import { getLogger } from '@huaqiu/dsh-plugin-log'
 import { createEdaHostClient, type EdaHostClient } from './client.js'
 import { hasHost, resolveEdaHostConfig, type EdaHostConfig } from './config.js'
 import { createNetListTools } from './tools.js'
-import { NetlistError } from './types.js'
 
 /** Plugin id — matches package.json. */
 export const name = '@huaqiu/dsh-eda-host'
 
-/** Cordis services this half depends on. */
-export const inject = ['tools'] as const
+/**
+ * Cordis services this half depends on.
+ *
+ * `hqEdge` is REQUIRED: the edge-bridge (the HOST) provides the node-side
+ * `hqEdge` service whose `baseUrl` is the loopback HQ Edge endpoint
+ * (`createNodeHqEdge(upstreamRoot, …)` → `get baseUrl()`). Without it the
+ * plugin cannot reach hq-edge at all — by design it cannot work standalone
+ * (the user-confirmed contract is "eda-host cannot work without hqEdge").
+ * Declaring it here is what lets `apply()` read `ctx.hqEdge` without Cordis
+ * throwing `cannot get property "hqEdge" without inject` (its context proxy
+ * walks the fiber tree and throws at the root fiber when the service was
+ * never injected into this plugin's fiber).
+ *
+ * `tools` is the DSH node runtime tool registry used to register the netlist
+ * tools.
+ */
+export const inject = ['hqEdge', 'tools'] as const
 
 export type { EdaHostConfig } from './config.js'
 export type { EdaHostClient } from './client.js'
@@ -48,6 +65,22 @@ export { NetlistError } from './types.js'
 declare module '@deepseek-ai/cordis' {
   interface Context {
     edaHost: EdaHostClient
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is the
+     * loopback HQ Edge endpoint, e.g. "http://localhost:18080". We read it
+     * lazily so this plugin does not hard-depend on the bridge and still works
+     * in standalone DSH installs (where the service is absent).
+     */
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is the
+     * loopback HQ Edge endpoint, e.g. "http://localhost:18080". This is a
+     * REQUIRED inject (see `export const inject` above): `apply()` reads
+     * `ctx.hqEdge` to resolve the endpoint, so the service must be present or
+     * Cordis throws `cannot get property "hqEdge" without inject`. When present
+     * but its `baseUrl` is empty, the netlist tools degrade to a clear
+     * FAILED_PRECONDITION rather than throwing at load time.
+     */
+    hqEdge: { baseUrl?: string }
   }
 }
 
@@ -58,10 +91,15 @@ const log = getLogger(COMPONENT)
 /**
  * Host plugin body — provide `edaHost` and register the three netlist tools.
  *
- * When no host base URL is configured, tools return ok:false with
- * error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
- * plugin can be installed in standalone DSH where hq-edge is absent, and the
- * tools degrade to a clear semantic message.
+ * The HQ Edge endpoint is resolved **lazily at request time** (see
+ * `getHqEdgeBaseUrl`): the edge-bridge plugin provides `ctx.hqEdge.baseUrl`,
+ * which wins over the static `config.hqEdgeBaseUrl` / `HQ_EDGE_BASE_URL` env
+ * fallback. This matches how `@huaqiu/dsh-artifacts` and `@huaqiu/dsh-tool-
+ * symbol-footprint` reach hq-edge, and means the URL is correct even when this
+ * plugin is applied before the bridge. When no host URL is available at call
+ * time, the tools degrade to a clear FAILED_PRECONDITION instead of throwing at
+ * load time — so the plugin still installs in standalone DSH where hq-edge is
+ * absent.
  *
  * @param ctx - real cordis context (node side).
  * @returns disposer — unregisters the tools on plugin dispose.
@@ -74,44 +112,21 @@ export function apply(ctx: Context, config: Partial<EdaHostConfig> = {}): () =>
   }
 
   const resolved = resolveEdaHostConfig(config)
+
+  // Late-bound host endpoint: prefer the edge-bridge service, then the overlay
+  // config / env value. Consulted on every request (see client.ts).
+  const getHqEdgeBaseUrl = (): string | undefined => {
+    const hq = ctx.hqEdge
+    return hq?.baseUrl && hq.baseUrl.trim().length > 0 ? hq.baseUrl : undefined
+  }
+
   log.info('applying dsh-eda-host node half', {
-    hasHost: hasHost(resolved),
-    hqEdgeBaseUrl: resolved.hqEdgeBaseUrl ?? null,
+    hasConfigHost: hasHost(resolved),
+    hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
     netlistPathPrefix: resolved.netlistPathPrefix,
   })
 
-  let client: EdaHostClient
-
-  if (hasHost(resolved)) {
-    client = createEdaHostClient(resolved)
-  } else {
-    // Standalone install (no hq-edge supervisor): every scope degrades to
-    // FAILED_PRECONDITION with a clear message.
-    const unavailable: EdaHostClient = {
-      getProjectNetlist: async () => {
-        throw new NetlistError(
-          'FAILED_PRECONDITION',
-          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
-            'netlist tools require the hq-edge EDA host bridge.',
-        )
-      },
-      getSelectionNetlist: async () => {
-        throw new NetlistError(
-          'FAILED_PRECONDITION',
-          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
-            'netlist tools require the hq-edge EDA host bridge.',
-        )
-      },
-      getActivePageNetlist: async () => {
-        throw new NetlistError(
-          'FAILED_PRECONDITION',
-          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
-            'netlist tools require the hq-edge EDA host bridge.',
-        )
-      },
-    }
-    client = unavailable
-  }
+  const client = createEdaHostClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl })
 
   ctx.effect(() => ctx.provide('edaHost', client))
 
@@ -121,7 +136,7 @@ export function apply(ctx: Context, config: Partial<EdaHostConfig> = {}): () =>
     disposers.push(ctx.tools.register(tool))
   }
 
-  log.info('dsh-eda-host node half ready', { tools: 3, hostMode: hasHost(resolved) })
+  log.info('dsh-eda-host node half ready', { tools: 3, configHostMode: hasHost(resolved) })
 
   return () => {
     for (const dispose of disposers) {