@huaqiu/dsh-artifacts 0.3.6 → 0.3.8

package/lib/index.d.mts

@@ -1,4 +1,5 @@
 import { ArtifactMeta, ArtifactType, CreateArtifactInput, CreateArtifactResult, HuaqiuArtifactService, HuaqiuArtifacts } from "./service.mjs";
+import { EditorType, PLACEABLE_ARTIFACT_TYPES, PlaceArtifactRequest, PlaceableArtifactType, canPlaceArtifact, parsePlaceableArtifactType } from "./placement.mjs";
 import { Context } from "@deepseek-ai/cordis";
 import { IncomingMessage, ServerResponse } from "node:http";
 //#region src/routes.d.ts
@@ -20,4 +21,4 @@ declare module '@deepseek-ai/cordis' {
 }
 declare function apply(ctx: Context, config?: HuaqiuArtifactsConfig): void;
 //#endregion
-export { ARTIFACTS_ROUTE_PREFIX, type ArtifactMeta, type ArtifactType, type ArtifactsHandler, type CreateArtifactInput, type CreateArtifactResult, HuaqiuArtifactService, type HuaqiuArtifacts, HuaqiuArtifactsConfig, apply, createArtifactsHandler, inject, name };
+export { ARTIFACTS_ROUTE_PREFIX, type ArtifactMeta, type ArtifactType, type ArtifactsHandler, type CreateArtifactInput, type CreateArtifactResult, type EditorType, HuaqiuArtifactService, type HuaqiuArtifacts, HuaqiuArtifactsConfig, PLACEABLE_ARTIFACT_TYPES, type PlaceArtifactRequest, type PlaceableArtifactType, apply, canPlaceArtifact, createArtifactsHandler, inject, name, parsePlaceableArtifactType };

package/lib/index.mjs

@@ -1,4 +1,5 @@
 import { HuaqiuArtifactService, log } from "./service.mjs";
+import { PLACEABLE_ARTIFACT_TYPES, canPlaceArtifact, parsePlaceableArtifactType } from "./placement.mjs";
 //#region src/routes.ts
 const ARTIFACTS_ROUTE_PREFIX = "/api/v1/huaqiu/artifacts";
 function sendJson(res, status, body) {
@@ -96,4 +97,4 @@ function apply(ctx, config = {}) {
 	});
 }
 //#endregion
-export { ARTIFACTS_ROUTE_PREFIX, HuaqiuArtifactService, apply, createArtifactsHandler, inject, name };
+export { ARTIFACTS_ROUTE_PREFIX, HuaqiuArtifactService, PLACEABLE_ARTIFACT_TYPES, apply, canPlaceArtifact, createArtifactsHandler, inject, name, parsePlaceableArtifactType };

package/lib/placement.d.mts

@@ -0,0 +1,82 @@
+//#region src/placement.d.ts
+/**
+ * Placement compatibility — shared by every generation tool that can produce
+ * a placeable EDA artifact (`component-gen-app`, `dsh-tool-schematic-gen`,
+ * `dsh-tool-symbol-footprint`).
+ *
+ * This is the **frontend** copy of the rule. It exists purely to decide whether
+ * to *render* the `Place` action. HQ Edge enforces the same matrix
+ * server-side, so this is never a security boundary — it is UX only.
+ *
+ * Deliberately NOT imported from HQ Edge: the frontend package owns its own
+ * compatibility helper (see the task's Phase 4 notes). The two matrices must
+ * stay in sync, so `canPlaceArtifact` is covered by a full-matrix test here.
+ *
+ * @module
+ */
+/** Artifact classes that can be placed into an EDA editor. */
+declare const PLACEABLE_ARTIFACT_TYPES: readonly ["schematic", "symbol", "footprint"];
+type PlaceableArtifactType = (typeof PLACEABLE_ARTIFACT_TYPES)[number];
+/**
+ * Editor contexts an HQ Edge instance may be serving.
+ * Mirrors HQ Edge's `EditorType` (`config/hostContext.ts`).
+ */
+type EditorType = 'sch' | 'pcb' | 'symbol' | 'footprint' | 'generic';
+/**
+ * Can `artifactType` be placed into the editor identified by `editorType`?
+ *
+ * Fails closed: an unrecognized artifact or editor type yields `false`.
+ */
+declare function canPlaceArtifact(artifactType: PlaceableArtifactType, editorType: EditorType): boolean;
+/**
+ * Coerce an unknown value to a {@link PlaceableArtifactType}, or `null` when
+ * it is not placeable (`pcb` and `zip` artifacts have no placement support).
+ */
+declare function parsePlaceableArtifactType(value: unknown): PlaceableArtifactType | null;
+/**
+ * The placement request the frontend sends to HQ Edge (via edge-bridge).
+ *
+ * It carries only *what* to place — never an editor type, target host, or EDA
+ * URL: HQ Edge owns all of that.
+ */
+interface PlaceArtifactRequest {
+  type: PlaceableArtifactType;
+  /** HQ Edge-resolvable URI — from `huaqiuArtifacts.getDownloadUri(id)`. */
+  artifactUri: string;
+  /** Original filename, when the URI path is opaque (e.g. `content`). */
+  filename?: string;
+  /** Root schematic filename — overrides the zip-derived root (system designs). */
+  root?: string;
+}
+/** Structural view of the `hqEdge` CLIENT service (edge-bridge browser half). */
+interface HqEdgePlaceLike {
+  context?: {
+    getCurrent?(): {
+      targetHost?: string;
+      editorType?: string;
+    } | null;
+    getTargetHost?(): string;
+    getEditorType?(): string;
+  };
+  placeArtifact?(request: PlaceArtifactRequest): Promise<unknown>;
+}
+/** Everything a card needs to render + fire the Place action, or null. */
+interface PlaceSupport {
+  editorType: string;
+  place(request: PlaceArtifactRequest): Promise<unknown>;
+}
+/**
+ * Build the Place support for `artifactType` from a lazily-resolved `hqEdge`.
+ *
+ * Returns null when `getHqEdge` is unavailable (standalone DSH has no
+ * edge-bridge, hence no `hqEdge` service). Otherwise returns a GETTER so
+ * callers resolve the service lazily — plugin load order and HQ Edge restarts
+ * both resolve correctly at click time. The getter yields null when
+ * placement is unavailable or the current editor cannot accept the artifact
+ * type (the card hides the button in that case).
+ *
+ * Editor gating is UX-only; HQ Edge re-enforces the matrix server-side (409).
+ */
+declare function placeSupportOf(getHqEdge: (() => HqEdgePlaceLike | undefined) | undefined, artifactType: PlaceableArtifactType): (() => PlaceSupport | null) | null;
+//#endregion
+export { EditorType, HqEdgePlaceLike, PLACEABLE_ARTIFACT_TYPES, PlaceArtifactRequest, PlaceSupport, PlaceableArtifactType, canPlaceArtifact, parsePlaceableArtifactType, placeSupportOf };

package/lib/placement.mjs

@@ -0,0 +1,93 @@
+//#region src/placement.ts
+/**
+* Placement compatibility — shared by every generation tool that can produce
+* a placeable EDA artifact (`component-gen-app`, `dsh-tool-schematic-gen`,
+* `dsh-tool-symbol-footprint`).
+*
+* This is the **frontend** copy of the rule. It exists purely to decide whether
+* to *render* the `Place` action. HQ Edge enforces the same matrix
+* server-side, so this is never a security boundary — it is UX only.
+*
+* Deliberately NOT imported from HQ Edge: the frontend package owns its own
+* compatibility helper (see the task's Phase 4 notes). The two matrices must
+* stay in sync, so `canPlaceArtifact` is covered by a full-matrix test here.
+*
+* @module
+*/
+/** Artifact classes that can be placed into an EDA editor. */
+const PLACEABLE_ARTIFACT_TYPES = [
+	"schematic",
+	"symbol",
+	"footprint"
+];
+/**
+* Editors each artifact type may be placed into.
+*
+* | Artifact  | sch | pcb | symbol | footprint | generic |
+* |-----------|-----|-----|--------|-----------|---------|
+* | schematic | yes | no  | no     | no        | no      |
+* | symbol    | yes | no  | yes    | no        | no      |
+* | footprint | no  | yes | no     | yes       | no      |
+*
+* `generic` appears in no row: HQ Edge may be inside *some* EDA host without
+* knowing which editor, so placement must fail closed.
+*/
+const COMPATIBLE_EDITORS = {
+	schematic: /* @__PURE__ */ new Set(["sch"]),
+	symbol: /* @__PURE__ */ new Set(["sch", "symbol"]),
+	footprint: /* @__PURE__ */ new Set(["pcb", "footprint"])
+};
+/**
+* Can `artifactType` be placed into the editor identified by `editorType`?
+*
+* Fails closed: an unrecognized artifact or editor type yields `false`.
+*/
+function canPlaceArtifact(artifactType, editorType) {
+	const allowed = COMPATIBLE_EDITORS[artifactType];
+	return allowed ? allowed.has(editorType) : false;
+}
+/**
+* Coerce an unknown value to a {@link PlaceableArtifactType}, or `null` when
+* it is not placeable (`pcb` and `zip` artifacts have no placement support).
+*/
+function parsePlaceableArtifactType(value) {
+	if (typeof value !== "string") return null;
+	return PLACEABLE_ARTIFACT_TYPES.includes(value) ? value : null;
+}
+/**
+* Build the Place support for `artifactType` from a lazily-resolved `hqEdge`.
+*
+* Returns null when `getHqEdge` is unavailable (standalone DSH has no
+* edge-bridge, hence no `hqEdge` service). Otherwise returns a GETTER so
+* callers resolve the service lazily — plugin load order and HQ Edge restarts
+* both resolve correctly at click time. The getter yields null when
+* placement is unavailable or the current editor cannot accept the artifact
+* type (the card hides the button in that case).
+*
+* Editor gating is UX-only; HQ Edge re-enforces the matrix server-side (409).
+*/
+function placeSupportOf(getHqEdge, artifactType) {
+	if (typeof getHqEdge !== "function") return null;
+	return () => {
+		let hqEdge;
+		try {
+			hqEdge = getHqEdge();
+		} catch {
+			return null;
+		}
+		if (!hqEdge || typeof hqEdge.placeArtifact !== "function") return null;
+		let editorType = "";
+		try {
+			editorType = hqEdge.context?.getEditorType?.() ?? hqEdge.context?.getCurrent?.()?.editorType ?? "";
+		} catch {
+			return null;
+		}
+		if (!editorType || !canPlaceArtifact(artifactType, editorType)) return null;
+		return {
+			editorType,
+			place: (request) => hqEdge.placeArtifact(request)
+		};
+	};
+}
+//#endregion
+export { PLACEABLE_ARTIFACT_TYPES, canPlaceArtifact, parsePlaceableArtifactType, placeSupportOf };

package/lib/service.d.mts

@@ -37,6 +37,18 @@ interface HuaqiuArtifacts {
   create(input: CreateArtifactInput): Promise<CreateArtifactResult>;
   get(id: string): Promise<ArtifactMeta | null>;
   readContent(id: string): Promise<Uint8Array | null>;
+  /**
+   * Stable URI for the artifact's bytes, suitable for handing to ANOTHER
+   * process (HQ Edge) — currently a `file://` URI to the stored content.
+   *
+   * An artifact **id** is store-local and must never cross that boundary: the
+   * DSH artifact store and the HQ Edge artifact store are separate, so an id
+   * minted here is meaningless there. Callers that need to reference an
+   * artifact across processes (e.g. the Place action) must pass this URI.
+   *
+   * @returns the URI, or null when the artifact is missing/expired.
+   */
+  getDownloadUri(id: string): Promise<string | null>;
   delete(id: string): Promise<void>;
   deleteAll(opts?: {
     onlyExpired?: boolean;
@@ -53,6 +65,17 @@ declare class HuaqiuArtifactService implements HuaqiuArtifacts {
   get(id: string): Promise<ArtifactMeta | null>;
   /** Returns `null` when missing or expired (miss signal for the HTTP 404). */
   readContent(id: string): Promise<Uint8Array | null>;
+  /**
+   * @see HuaqiuArtifacts.getDownloadUri
+   *
+   * Returns a `file://` URI rather than an HTTP URL: this package has no
+   * knowledge of the DSH origin/port it will eventually be served from, and
+   * HQ Edge runs on the same host, so a filesystem URI is the narrowest
+   * boundary that is actually resolvable on the other side. HQ Edge also
+   * accepts `http(s)://` URIs, so this can be upgraded without a contract
+   * change.
+   */
+  getDownloadUri(id: string): Promise<string | null>;
   delete(id: string): Promise<void>;
   deleteAll(opts?: {
     onlyExpired?: boolean;

package/lib/service.mjs

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 //#region src/service.ts
@@ -137,6 +138,28 @@ var HuaqiuArtifactService = class {
 			return null;
 		}
 	}
+	/**
+	* @see HuaqiuArtifacts.getDownloadUri
+	*
+	* Returns a `file://` URI rather than an HTTP URL: this package has no
+	* knowledge of the DSH origin/port it will eventually be served from, and
+	* HQ Edge runs on the same host, so a filesystem URI is the narrowest
+	* boundary that is actually resolvable on the other side. HQ Edge also
+	* accepts `http(s)://` URIs, so this can be upgraded without a contract
+	* change.
+	*/
+	async getDownloadUri(id) {
+		if (!await this.get(id)) return null;
+		try {
+			return pathToFileURL(path.join(this.artifactDir(id), "content")).href;
+		} catch (err) {
+			log("warn", "getDownloadUri failed", {
+				id,
+				err
+			});
+			return null;
+		}
+	}
 	async delete(id) {
 		if (typeof id !== "string" || !ARTIFACT_ID_PATTERN.test(id)) return;
 		try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-artifacts",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -9,6 +9,10 @@
       "types": "./lib/index.d.mts",
       "default": "./lib/index.mjs"
     },
+    "./placement": {
+      "types": "./lib/placement.d.mts",
+      "default": "./lib/placement.mjs"
+    },
     "./service": {
       "types": "./lib/service.d.mts",
       "default": "./lib/service.mjs"

package/src/index.ts

@@ -20,6 +20,17 @@ export type {
 export { HuaqiuArtifactService } from './service.js'
 export { ARTIFACTS_ROUTE_PREFIX, createArtifactsHandler, type ArtifactsHandler } from './routes.js'
 
+// Placement compatibility — shared by the generation tools so none of them
+// re-derives the artifact × editor matrix on its own.
+export {
+  PLACEABLE_ARTIFACT_TYPES,
+  canPlaceArtifact,
+  parsePlaceableArtifactType,
+  type PlaceableArtifactType,
+  type EditorType,
+  type PlaceArtifactRequest,
+} from './placement.js'
+
 export const name = '@huaqiu/dsh-artifacts'
 export const inject = ['webServer'] as const
 

package/src/placement.ts

@@ -0,0 +1,141 @@
+/**
+ * Placement compatibility — shared by every generation tool that can produce
+ * a placeable EDA artifact (`component-gen-app`, `dsh-tool-schematic-gen`,
+ * `dsh-tool-symbol-footprint`).
+ *
+ * This is the **frontend** copy of the rule. It exists purely to decide whether
+ * to *render* the `Place` action. HQ Edge enforces the same matrix
+ * server-side, so this is never a security boundary — it is UX only.
+ *
+ * Deliberately NOT imported from HQ Edge: the frontend package owns its own
+ * compatibility helper (see the task's Phase 4 notes). The two matrices must
+ * stay in sync, so `canPlaceArtifact` is covered by a full-matrix test here.
+ *
+ * @module
+ */
+
+/** Artifact classes that can be placed into an EDA editor. */
+export const PLACEABLE_ARTIFACT_TYPES = ['schematic', 'symbol', 'footprint'] as const
+
+export type PlaceableArtifactType = (typeof PLACEABLE_ARTIFACT_TYPES)[number]
+
+/**
+ * Editor contexts an HQ Edge instance may be serving.
+ * Mirrors HQ Edge's `EditorType` (`config/hostContext.ts`).
+ */
+export type EditorType = 'sch' | 'pcb' | 'symbol' | 'footprint' | 'generic'
+
+/**
+ * Editors each artifact type may be placed into.
+ *
+ * | Artifact  | sch | pcb | symbol | footprint | generic |
+ * |-----------|-----|-----|--------|-----------|---------|
+ * | schematic | yes | no  | no     | no        | no      |
+ * | symbol    | yes | no  | yes    | no        | no      |
+ * | footprint | no  | yes | no     | yes       | no      |
+ *
+ * `generic` appears in no row: HQ Edge may be inside *some* EDA host without
+ * knowing which editor, so placement must fail closed.
+ */
+const COMPATIBLE_EDITORS: Record<PlaceableArtifactType, ReadonlySet<EditorType>> = {
+  schematic: new Set<EditorType>(['sch']),
+  symbol: new Set<EditorType>(['sch', 'symbol']),
+  footprint: new Set<EditorType>(['pcb', 'footprint']),
+}
+
+/**
+ * Can `artifactType` be placed into the editor identified by `editorType`?
+ *
+ * Fails closed: an unrecognized artifact or editor type yields `false`.
+ */
+export function canPlaceArtifact(
+  artifactType: PlaceableArtifactType,
+  editorType: EditorType,
+): boolean {
+  const allowed = COMPATIBLE_EDITORS[artifactType]
+  return allowed ? allowed.has(editorType) : false
+}
+
+/**
+ * Coerce an unknown value to a {@link PlaceableArtifactType}, or `null` when
+ * it is not placeable (`pcb` and `zip` artifacts have no placement support).
+ */
+export function parsePlaceableArtifactType(value: unknown): PlaceableArtifactType | null {
+  if (typeof value !== 'string') return null
+  return (PLACEABLE_ARTIFACT_TYPES as readonly string[]).includes(value)
+    ? (value as PlaceableArtifactType)
+    : null
+}
+
+/**
+ * The placement request the frontend sends to HQ Edge (via edge-bridge).
+ *
+ * It carries only *what* to place — never an editor type, target host, or EDA
+ * URL: HQ Edge owns all of that.
+ */
+export interface PlaceArtifactRequest {
+  type: PlaceableArtifactType
+  /** HQ Edge-resolvable URI — from `huaqiuArtifacts.getDownloadUri(id)`. */
+  artifactUri: string
+  /** Original filename, when the URI path is opaque (e.g. `content`). */
+  filename?: string
+  /** Root schematic filename — overrides the zip-derived root (system designs). */
+  root?: string
+}
+
+// ── hqEdge place seam ───────────────────────────────────────────────────────
+
+/** Structural view of the `hqEdge` CLIENT service (edge-bridge browser half). */
+export interface HqEdgePlaceLike {
+  context?: {
+    getCurrent?(): { targetHost?: string; editorType?: string } | null
+    getTargetHost?(): string
+    getEditorType?(): string
+  }
+  placeArtifact?(request: PlaceArtifactRequest): Promise<unknown>
+}
+
+/** Everything a card needs to render + fire the Place action, or null. */
+export interface PlaceSupport {
+  editorType: string
+  place(request: PlaceArtifactRequest): Promise<unknown>
+}
+
+/**
+ * Build the Place support for `artifactType` from a lazily-resolved `hqEdge`.
+ *
+ * Returns null when `getHqEdge` is unavailable (standalone DSH has no
+ * edge-bridge, hence no `hqEdge` service). Otherwise returns a GETTER so
+ * callers resolve the service lazily — plugin load order and HQ Edge restarts
+ * both resolve correctly at click time. The getter yields null when
+ * placement is unavailable or the current editor cannot accept the artifact
+ * type (the card hides the button in that case).
+ *
+ * Editor gating is UX-only; HQ Edge re-enforces the matrix server-side (409).
+ */
+export function placeSupportOf(
+  getHqEdge: (() => HqEdgePlaceLike | undefined) | undefined,
+  artifactType: PlaceableArtifactType,
+): (() => PlaceSupport | null) | null {
+  if (typeof getHqEdge !== 'function') return null
+  return () => {
+    let hqEdge: HqEdgePlaceLike | undefined
+    try {
+      hqEdge = getHqEdge()
+    } catch {
+      return null
+    }
+    if (!hqEdge || typeof hqEdge.placeArtifact !== 'function') return null
+    let editorType = ''
+    try {
+      editorType = hqEdge.context?.getEditorType?.() ?? hqEdge.context?.getCurrent?.()?.editorType ?? ''
+    } catch {
+      return null
+    }
+    if (!editorType || !canPlaceArtifact(artifactType, editorType as EditorType)) return null
+    return {
+      editorType,
+      place: (request) => hqEdge.placeArtifact!(request),
+    }
+  }
+}

package/src/service.ts

@@ -19,6 +19,7 @@
  */
 import * as fs from 'node:fs'
 import * as path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { randomUUID } from 'node:crypto'
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
 
@@ -67,6 +68,18 @@ export interface HuaqiuArtifacts {
   create(input: CreateArtifactInput): Promise<CreateArtifactResult>
   get(id: string): Promise<ArtifactMeta | null>
   readContent(id: string): Promise<Uint8Array | null>
+  /**
+   * Stable URI for the artifact's bytes, suitable for handing to ANOTHER
+   * process (HQ Edge) — currently a `file://` URI to the stored content.
+   *
+   * An artifact **id** is store-local and must never cross that boundary: the
+   * DSH artifact store and the HQ Edge artifact store are separate, so an id
+   * minted here is meaningless there. Callers that need to reference an
+   * artifact across processes (e.g. the Place action) must pass this URI.
+   *
+   * @returns the URI, or null when the artifact is missing/expired.
+   */
+  getDownloadUri(id: string): Promise<string | null>
   delete(id: string): Promise<void>
   deleteAll(opts?: { onlyExpired?: boolean }): Promise<number>
 }
@@ -211,6 +224,27 @@ export class HuaqiuArtifactService implements HuaqiuArtifacts {
     }
   }
 
+  /**
+   * @see HuaqiuArtifacts.getDownloadUri
+   *
+   * Returns a `file://` URI rather than an HTTP URL: this package has no
+   * knowledge of the DSH origin/port it will eventually be served from, and
+   * HQ Edge runs on the same host, so a filesystem URI is the narrowest
+   * boundary that is actually resolvable on the other side. HQ Edge also
+   * accepts `http(s)://` URIs, so this can be upgraded without a contract
+   * change.
+   */
+  async getDownloadUri(id: string): Promise<string | null> {
+    const meta = await this.get(id)
+    if (!meta) return null
+    try {
+      return pathToFileURL(path.join(this.artifactDir(id), 'content')).href
+    } catch (err) {
+      log('warn', 'getDownloadUri failed', { id, err })
+      return null
+    }
+  }
+
   async delete(id: string): Promise<void> {
     if (typeof id !== 'string' || !ARTIFACT_ID_PATTERN.test(id)) return
     try {