@huaqiu/dsh-eda-host 0.3.24 → 0.4.1

package/README.md

@@ -1,16 +1,30 @@
 # @huaqiu/dsh-eda-host
 
-DSH plugin exposing the current EDA host's schematic netlist to agents through
-hq-edge.
+DSH plugin exposing the current EDA host to agents through hq-edge: its
+schematic netlist, and — without reimplementing anything — the environment and
+capability facts the host already knows.
 
 ## What it provides
 
+Netlist:
+
 | Tool | Scope |
 |---|---|
 | `get_project_netlist` | complete logical netlist of the current project |
 | `get_selection_netlist` | netlist of the currently selected components |
 | `get_active_page_netlist` | netlist of the active schematic page |
 
+EDA host discovery:
+
+| Tool | Returns |
+|---|---|
+| `get_eda_host_info` | host identity, version, installation paths, `kicad-cli` path |
+| `get_eda_host_capabilities` | capabilities the *current* host can actually provide |
+
+Discovery is not implementation: a capability is advertised only when the host
+can already provide it, and never because the EDA application is generally
+known for it.
+
 Each tool returns lossless JSON:
 
 ```json
@@ -42,7 +56,12 @@ NOT an error. On failure the tool returns `ok: false` with a semantic
 - `UNIMPLEMENTED` — the host does not support this scope (e.g. active page on
   KiCad). Do not retry.
 - `UNAVAILABLE` — hq-edge host unreachable.
-- `INTERNAL` — host-side failure.
+- `DEADLINE_EXCEEDED` — the host did not answer within the request budget.
+- `INTERNAL` — host-side failure or a malformed response.
+
+`ok:true` with empty `components`/`nets` means exactly one thing: a genuinely
+empty design. It never means "the parse failed" or "the host is unavailable" —
+those are always `ok:false` with a `kind`.
 
 ## Architecture
 
@@ -58,9 +77,45 @@ EDA Host          (hq.ir.schematic.v1.NetListService — KiCad / HQ EDA)
 native EDA model
 ```
 
-- No `@hqedge/*` dependency: the base URL arrives as overlay config
-  (`hqEdgeBaseUrl`, delivered by the hq-edge supervisor) or `HQ_EDGE_BASE_URL`
-  env fallback.
+- No `@hqedge/*` dependency: the base URL is read from `ctx.hqEdge.baseUrl`
+  (provided by the edge-bridge), falling back to overlay config
+  (`hqEdgeBaseUrl`) or `HQ_EDGE_BASE_URL`.
 - No KiCad code, no schematic parsing, no host IPC in this package.
 - Errors are propagated with semantic kinds — never converted into fake empty
   netlists.
+
+## EDA host discovery
+
+Host info crosses the same boundary as the netlist, using the EDA-independent
+`hq.host.v1` contract — not KiCad-shaped messages:
+
+```text
+get_eda_host_info ─┐
+                   ├─→ hq-edge /api/v1/host/* ─→ hq.host.v1.EdaHostInfoService ─→ host
+get_eda_host_capabilities ─┘
+```
+
+The host adapts its native facts (version, install path, `kicad-cli` location,
+which editors are open) into that contract. hq-edge performs no host-specific
+translation, so KiCad and HQ EDA implement the same service.
+
+**`hq.host.v1` has no availability fields.** A host that answers is available,
+and every executable it lists is one it can run — so unavailability is never a
+flag to check, it is a failed request (`ok:false` with `UNAVAILABLE` /
+`FAILED_PRECONDITION` / `DEADLINE_EXCEEDED`). Because proto3 omits default
+values, a host reporting nothing arrives as `{}`; the client fills the proto3
+defaults so a missing field can never be misread as "unavailable". An empty
+executable `path` means the host did not resolve an absolute location, not that
+the tool is missing.
+
+## Request budget
+
+Every request has a single bounded budget (`requestTimeoutMs`, default 30 s),
+enforced here and mirrored by the KiCad UI-dispatch bound. A request that
+exceeds it fails with `DEADLINE_EXCEEDED`; it never returns an empty result.
+
+## Dependency boundary
+
+This plugin **requires hq-edge**. It is not a standalone DSH plugin: `hqEdge` is
+a required inject, and `apply()` throws if the bridge did not provide a usable
+endpoint. See `docs/tasks/expose-capability.md` in hq-edge.

package/lib/index.d.mts

@@ -16,6 +16,19 @@ interface EdaHostConfig {
   hqEdgeBaseUrl?: string;
   /** Path prefix on the host; default "/api/v1/netlist". */
   netlistPathPrefix?: string;
+  /** Path prefix for PCB selection; default "/api/v1/pcb-selection". */
+  pcbSelectionPathPrefix?: string;
+  /** Path prefix for host discovery; default "/api/v1/host". */
+  hostPathPrefix?: string;
+  /**
+   * End-to-end budget for one EDA-host request, in milliseconds.
+   *
+   * This is the SINGLE request budget for the whole chain — the plugin does
+   * not define separate per-layer timeouts. It is enforced here (outermost)
+   * and mirrored by the KiCad UI-dispatch bound, so no agent request can wait
+   * indefinitely. See docs/tasks/expose-capability.md §6.
+   */
+  requestTimeoutMs?: number;
 }
 //#endregion
 //#region src/types.d.ts
@@ -57,6 +70,123 @@ interface SchematicNetlist {
   components: SchematicComponent[];
   nets: ElectricalNet[];
 }
+/**
+ * Semantic PCB selection types.
+ *
+ * Self-contained structural mirror of `hq.pcb.v1` (the hq-edge-owned semantic
+ * protobuf contract for `PcbSelectionService.GetSelection`). Units follow the
+ * hq.pcb.v1 convention: positions/sizes/lengths in mm, rotations in degrees,
+ * `id` is the KiCad native object identity.
+ */
+interface PcbPoint {
+  x: number;
+  y: number;
+}
+interface PcbNetRef {
+  name: string;
+  code: number;
+}
+interface PcbPad {
+  id: string;
+  pin: string;
+  type: string;
+  shape: string;
+  position?: PcbPoint;
+  widthMm: number;
+  heightMm: number;
+  rotationDeg: number;
+  layer: string;
+  net?: PcbNetRef;
+}
+interface PcbFootprint {
+  id: string;
+  reference: string;
+  value: string;
+  footprint: string;
+  position?: PcbPoint;
+  rotationDeg: number;
+  pads: PcbPad[];
+}
+interface PcbTrack {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  widthMm: number;
+  lengthMm: number;
+  net?: PcbNetRef;
+}
+interface PcbArc {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  mid?: PcbPoint;
+  net?: PcbNetRef;
+}
+interface PcbVia {
+  id: string;
+  layers: string[];
+  drillMm: number;
+  viaType: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+}
+interface PcbSegment {
+  start?: PcbPoint;
+  end?: PcbPoint;
+}
+interface PcbZone {
+  id: string;
+  layer: string;
+  net?: PcbNetRef;
+  outline: PcbSegment[];
+}
+interface PcbShape {
+  id: string;
+  layer: string;
+  shapeType: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  center?: PcbPoint;
+  radiusMm: number;
+  mid?: PcbPoint;
+  widthMm: number;
+}
+interface PcbText {
+  id: string;
+  layer: string;
+  text: string;
+  position?: PcbPoint;
+  rotationDeg: number;
+  hJustify: string;
+  vJustify: string;
+}
+interface PcbDimension {
+  id: string;
+  layer: string;
+  start?: PcbPoint;
+  end?: PcbPoint;
+  value: string;
+  dimType: string;
+}
+interface PcbGroup {
+  id: string;
+  itemIds: string[];
+}
+interface PcbSelection {
+  footprints: PcbFootprint[];
+  pads: PcbPad[];
+  tracks: PcbTrack[];
+  arcs: PcbArc[];
+  vias: PcbVia[];
+  zones: PcbZone[];
+  shapes: PcbShape[];
+  texts: PcbText[];
+  dimensions: PcbDimension[];
+  groups: PcbGroup[];
+  nets: PcbNetRef[];
+}
 /**
  * Semantic error categories for netlist retrieval. Mirrors the gRPC status
  * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish
@@ -70,21 +200,117 @@ type NetlistErrorKind =
 /** Host-side runtime failure. */
 'INTERNAL' |
 /** Host unavailable (connection refused). */
-'UNAVAILABLE';
+'UNAVAILABLE' |
+/** The host did not answer within the request budget. */
+'DEADLINE_EXCEEDED';
 declare class NetlistError extends Error {
   readonly kind: NetlistErrorKind;
   constructor(kind: NetlistErrorKind, message: string);
 }
+/**
+ * `hq.host.v1` carries **no availability flags**.
+ *
+ * A host that answers `GetEdaHostInfo` is, by definition, available, and every
+ * executable it lists is one it can actually run. Unavailability is therefore
+ * never a field to check — it is a failed request, surfaced as `ok:false` with
+ * `error.kind` `UNAVAILABLE` / `FAILED_PRECONDITION` / `DEADLINE_EXCEEDED`.
+ *
+ * Consequence for consumers: never infer "unavailable" from a missing or empty
+ * value. Absence of `identity`/`installation` just means proto3 omitted
+ * defaults (see `parseEdaHostInfo`), and empty `path` only means the host could
+ * not resolve an absolute location — the tool is still runnable by name.
+ */
+/**
+ * Which EDA application sits behind the semantic host boundary.
+ *
+ * Deliberately EDA-independent: a new host adds a value here rather than
+ * introducing host-specific messages or tools.
+ */
+type EdaHostType = 'EDA_HOST_TYPE_UNSPECIFIED' | 'EDA_HOST_TYPE_KICAD' | 'EDA_HOST_TYPE_HQ_EDA';
+/**
+ * A capability an EDA host may provide.
+ *
+ * A capability is advertised only when the host can actually provide it —
+ * discovering a capability is not the same as implementing it. Unknown values
+ * MUST be treated as "not supported" so a newer host cannot confuse an older
+ * plugin.
+ */
+type EdaHostCapability = 'EDA_HOST_CAPABILITY_UNSPECIFIED' | 'EDA_HOST_CAPABILITY_SCHEMATIC' | 'EDA_HOST_CAPABILITY_PCB' | 'EDA_HOST_CAPABILITY_NETLIST' | 'EDA_HOST_CAPABILITY_NETLIST_SELECTION' | 'EDA_HOST_CAPABILITY_NETLIST_ACTIVE_PAGE' | 'EDA_HOST_CAPABILITY_ERC' | 'EDA_HOST_CAPABILITY_DRC' | 'EDA_HOST_CAPABILITY_BOM' | 'EDA_HOST_CAPABILITY_PLACEMENT';
+/** A host-provided command line tool. */
+interface EdaHostExecutable {
+  /** Stable tool name, e.g. "kicad-cli". */
+  name: string;
+  /**
+   * Absolute path when the host could resolve one.
+   *
+   * Empty means "resolvable by name only" (e.g. found on `PATH` but the host
+   * did not report a location) — never "not installed" or "unusable".
+   */
+  path: string;
+}
+/** Where the host application lives on disk. */
+interface EdaHostInstallation {
+  applicationPath: string;
+  /**
+   * Executables the host can run. Being listed here IS the availability
+   * signal: there is no per-executable availability flag.
+   */
+  executables: EdaHostExecutable[];
+}
+/** Which EDA host is connected. */
+interface EdaHostIdentity {
+  hostType: EdaHostType;
+  hostName: string;
+  version: string;
+}
+/**
+ * EDA-independent description of the connected host.
+ *
+ * Answering this message is the host's way of saying it is available — there is
+ * no `available` field to inspect.
+ */
+interface EdaHostInfo {
+  identity: EdaHostIdentity;
+  installation: EdaHostInstallation;
+}
 //#endregion
 //#region src/client.d.ts
+/** Per-call options. `signal` lets DSH cancel a request (see §6 of the task). */
+interface EdaHostRequestOptions {
+  signal?: AbortSignal;
+}
 interface EdaHostClient {
   /** Netlist of the currently selected components. */
-  getSelectionNetlist(): Promise<SchematicNetlist>;
+  getSelectionNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
   /** Complete logical netlist for the current project. */
-  getProjectNetlist(): Promise<SchematicNetlist>;
+  getProjectNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
   /** Netlist of the current active schematic page. */
-  getActivePageNetlist(): Promise<SchematicNetlist>;
+  getActivePageNetlist(options?: EdaHostRequestOptions): Promise<SchematicNetlist>;
+  /**
+   * EDA-independent identity / installation of the host. Presence of a result
+   * is the availability signal — `hq.host.v1` has no availability field.
+   */
+  getEdaHostInfo(options?: EdaHostRequestOptions): Promise<EdaHostInfo>;
+  /** Capabilities the host currently provides. */
+  getEdaHostCapabilities(options?: EdaHostRequestOptions): Promise<EdaHostCapability[]>;
+  /**
+   * Semantic PCB selection of the current PCB editor (hq.pcb.v1
+   * PcbSelectionService.GetSelection bridged through hq-edge). An empty
+   * selection resolves to an all-empty `PcbSelection` — never an error.
+   */
+  getPcbSelection(options?: EdaHostRequestOptions): Promise<PcbSelection>;
 }
+/**
+ * Extract the semantic `SchematicNetlist` from an hq-edge netlist body.
+ *
+ * hq-edge now emits a single-level body: `{ netlist: { components, nets } }`.
+ * Older hq-edge builds serialized the protobuf envelope
+ * (`GetNetListResponse.oneof result`), which produced a second `netlist` level
+ * and made every populated design look empty. That legacy shape is unwrapped
+ * EXPLICITLY — not silently — and anything else is a hard error, because
+ * "malformed" must never masquerade as "empty design".
+ */
+declare function parseNetlistBody(body: unknown): SchematicNetlist;
 //#endregion
 //#region src/index.d.ts
 /** Plugin id — matches package.json. */
@@ -147,4 +373,4 @@ declare module '@deepseek-ai/cordis' {
  */
 declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
 //#endregion
-export { type EdaHostClient, type EdaHostConfig, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name };
+export { type EdaHostCapability, type EdaHostClient, type EdaHostConfig, type EdaHostExecutable, type EdaHostIdentity, type EdaHostInfo, type EdaHostInstallation, type EdaHostRequestOptions, type EdaHostType, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PcbArc, type PcbDimension, type PcbFootprint, type PcbGroup, type PcbNetRef, type PcbPad, type PcbPoint, type PcbSegment, type PcbSelection, type PcbShape, type PcbText, type PcbTrack, type PcbVia, type PcbZone, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name, parseNetlistBody };