@huaqiu/component-gen-server 0.3.6

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@huaqiu/component-gen-server",
+  "version": "0.3.6",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./standalone": {
+      "default": "./lib/standalone.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "bin": {
+    "hq-component-gen": "./lib/standalone.mjs"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.0",
+    "@huaqiu/dsh-artifacts": "0.3.6",
+    "@huaqiu/dsh-auth": "0.3.6"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.0",
+    "@huaqiu/dsh-tool-symbol-footprint": "^0.3.6"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0",
+    "@huaqiu/dsh-tool-symbol-footprint": "0.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/backend.ts

@@ -0,0 +1,33 @@
+/**
+ * `@huaqiu/component-gen-server` — generation backend seam.
+ *
+ * The server never reimplements generation. It only defines the seam; the
+ * `@huaqiu/dsh-tool-symbol-footprint` plugin provides the real implementation
+ * (`createComponentGenBackend`) wired to its existing `runGenerate*` functions
+ * + `SymbolFootprintEnv`. The standalone server builds the same backend from
+ * the plugin's exports. Results are the raw tool-body outcomes:
+ *
+ *   symbol            → { status:'generated', kind:'symbol', fileUrl, filename, artifact?, … }
+ *   extract-footprint → { status:'needs_confirmation', pkgType, fileName, dimensions, … }
+ *                       | { status:'generated', kind:'footprint', autoGenerated:true, … }
+ *   generate-footprint→ { status:'generated', kind:'footprint', pkgType, dimensions, … }
+ *
+ * `needs_auth` (the tool body's unauthenticated result) is mapped by the job
+ * runner to a failed job with the `needs_auth` marker so the UI can re-trigger
+ * login.
+ */
+import type { JobKind } from './types.js'
+
+export interface GenerationExec {
+  signal?: AbortSignal
+}
+
+export interface ComponentGenBackend {
+  generateSymbol(args: { imageDataUrl: string; instruction?: string }, exec: GenerationExec): Promise<Record<string, unknown>>
+  extractFootprint(args: { imageDataUrl: string; packageType?: string; instruction?: string }, exec: GenerationExec): Promise<Record<string, unknown>>
+  generateFootprint(args: { packageType: string; fileName?: string; dimensions: Record<string, number> }, exec: GenerationExec): Promise<Record<string, unknown>>
+}
+
+export function kindLabel(kind: JobKind): 'symbol' | 'footprint' {
+  return kind === 'symbol' ? 'symbol' : 'footprint'
+}

package/src/history.ts

@@ -0,0 +1,135 @@
+/**
+ * `@huaqiu/component-gen-server` — history store.
+ *
+ * Plain filesystem (no SQLite): `<dir>/history.json` + `<dir>/inputs/<id>`.
+ * History is user-level (not project-level). Entries are appended by the job
+ * runner on terminal states; input thumbnails are stored by the routes layer
+ * at POST /jobs time. `imageId` in an entry's `input` points into `inputs/`.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { HistoryEntry, HistoryPage, HistoryPatch, HistoryQuery } from './types.js'
+
+const INPUT_DIR = 'inputs'
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  try {
+    if (!existsSync(path)) return fallback
+    return JSON.parse(readFileSync(path, 'utf8')) as T
+  } catch {
+    return fallback
+  }
+}
+
+function writeJsonFile(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(value, null, 2), 'utf8')
+}
+
+/** `data:image/...;base64,....` → { mime, bytes } | null. */
+export function parseDataUrl(dataUrl: string): { mime: string; bytes: Buffer } | null {
+  const m = /^data:([^;,]+);base64,(.+)$/s.exec(dataUrl)
+  if (!m) return null
+  try {
+    return { mime: m[1]!, bytes: Buffer.from(m[2]!, 'base64') }
+  } catch {
+    return null
+  }
+}
+
+export class HistoryStore {
+  private readonly dir: string
+  private readonly file: string
+  private entries: HistoryEntry[] = []
+
+  constructor(dir: string) {
+    this.dir = dir
+    this.file = join(dir, 'history.json')
+    this.entries = readJsonFile<HistoryEntry[]>(this.file, [])
+  }
+
+  /** All entries, newest first. */
+  private sorted(): HistoryEntry[] {
+    return [...this.entries].sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
+  }
+
+  async append(entry: HistoryEntry): Promise<HistoryEntry> {
+    this.entries = [entry, ...this.entries.filter((e) => e.id !== entry.id)]
+    writeJsonFile(this.file, this.entries)
+    return entry
+  }
+
+  async list(query: HistoryQuery): Promise<HistoryPage> {
+    const limit = Math.max(1, Math.min(100, query.limit ?? 20))
+    const sorted = this.sorted()
+    const start = query.cursor ? sorted.findIndex((e) => e.id === query.cursor) + 1 : 0
+    const slice = start < 0 ? [] : sorted.slice(start, start + limit)
+    const next = start + slice.length < sorted.length ? slice[slice.length - 1]?.id ?? null : null
+    return { entries: slice, nextCursor: next }
+  }
+
+  async get(id: string): Promise<HistoryEntry | null> {
+    return this.entries.find((e) => e.id === id) ?? null
+  }
+
+  async patch(id: string, patch: HistoryPatch): Promise<HistoryEntry | null> {
+    const idx = this.entries.findIndex((e) => e.id === id)
+    if (idx < 0) return null
+    const current = this.entries[idx]!
+    const next: HistoryEntry = {
+      ...current,
+      ...(patch.status !== undefined ? { status: patch.status } : {}),
+      ...(patch.error !== undefined ? { error: patch.error } : {}),
+      ...(patch.edited !== undefined ? { edited: patch.edited } : {}),
+      ...(patch.result !== undefined ? { result: patch.result } : {}),
+    }
+    this.entries[idx] = next
+    writeJsonFile(this.file, this.entries)
+    return next
+  }
+
+  async delete(id: string): Promise<void> {
+    const entry = this.entries.find((e) => e.id === id)
+    this.entries = this.entries.filter((e) => e.id !== id)
+    writeJsonFile(this.file, this.entries)
+    if (entry?.input?.imageId) {
+      try { unlinkSync(join(this.dir, INPUT_DIR, entry.input.imageId)) } catch { /* already gone */ }
+      try { unlinkSync(join(this.dir, INPUT_DIR, `${entry.input.imageId}.mime`)) } catch { /* already gone */ }
+    }
+  }
+
+  // ── input thumbnails ──────────────────────────────────────────────────────
+  // Bytes are stored as `<imageId>`; the original media type in a `<imageId>.mime`
+  // sidecar so reopen serves pasted/selected JPEG/WebP/… images correctly (the
+  // local file the user pasted may be long gone — this copy is authoritative).
+
+  async saveImage(imageId: string, dataUrl: string): Promise<void> {
+    const parsed = parseDataUrl(dataUrl)
+    if (!parsed) throw new Error('component-gen: invalid image data URL')
+    const dir = join(this.dir, INPUT_DIR)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, imageId), parsed.bytes)
+    writeFileSync(join(dir, `${imageId}.mime`), parsed.mime, 'utf8')
+  }
+
+  async readImage(imageId: string): Promise<{ bytes: Uint8Array; mime: string } | null> {
+    const dir = join(this.dir, INPUT_DIR)
+    const path = join(dir, imageId)
+    if (!existsSync(path)) return null
+    let mime = 'image/png'
+    try {
+      const sidecar = readFileSync(join(dir, `${imageId}.mime`), 'utf8').trim()
+      if (sidecar) mime = sidecar
+    } catch { /* legacy entry stored before the mime sidecar existed */ }
+    return { bytes: readFileSync(path), mime }
+  }
+}
+
+export function newHistoryId(): string {
+  return `hst_${randomUUID().slice(0, 18)}`
+}
+
+export function newImageId(): string {
+  return `img_${randomUUID().slice(0, 18)}`
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * `@huaqiu/component-gen-server` — public API.
+ *
+ * The shared component-gen HTTP surface. The DSH plugin mounts
+ * `createComponentGenRoutes(deps)` on its `webServer`; the standalone server
+ * (./standalone) wires the same routes + dsh-auth + dsh-artifacts + app bundle
+ * into one node:http server.
+ */
+export {
+  createComponentGenHandler,
+  type ComponentGenHandler,
+  type ComponentGenHandlerDeps,
+} from './routes.js'
+export { JobStore, runGeneration, type JobMeta, type RunOutcome } from './jobs.js'
+export { HistoryStore, parseDataUrl, newHistoryId, newImageId } from './history.js'
+export type { ComponentGenBackend, GenerationExec } from './backend.js'
+export {
+  COMPONENT_GEN_ROUTE_PREFIX,
+  MAX_IMAGE_BYTES,
+  type ComponentGenConfig,
+  type ComponentGenPage,
+  type HistoryEntry,
+  type HistoryPage,
+  type HistoryPatch,
+  type HistoryQuery,
+  type JobEvent,
+  type JobInput,
+  type JobKind,
+  type JobState,
+  type StartJobRequest,
+} from './types.js'
+import { createComponentGenHandler, type ComponentGenHandlerDeps } from './routes.js'
+import { COMPONENT_GEN_ROUTE_PREFIX } from './types.js'
+
+export interface ComponentGenWebRoute {
+  kind: 'prefix'
+  path: string
+  handler: ReturnType<typeof createComponentGenHandler>
+}
+
+/** Build the DSH `webServer.register(...)` route object. */
+export function createComponentGenRoutes(deps: ComponentGenHandlerDeps): ComponentGenWebRoute {
+  return {
+    kind: 'prefix',
+    path: COMPONENT_GEN_ROUTE_PREFIX,
+    handler: createComponentGenHandler(deps),
+  }
+}

package/src/jobs.ts

@@ -0,0 +1,279 @@
+/**
+ * `@huaqiu/component-gen-server` — in-memory job store + generation runner.
+ *
+ * Jobs live in memory (no persistent queue). Each job is driven by the
+ * injected generation backend and reports through SSE events. On a terminal
+ * state the runner appends a history entry (generated / failed / cancelled).
+ * The `needs_confirmation` phase is a PAUSE: the job reports the extracted
+ * dimensions and waits — the app then starts a separate `generate-footprint`
+ * job with the human-approved values (single-HIL: a footprint is generated
+ * only from dimensions a human has seen).
+ */
+import type { ComponentGenBackend } from './backend.js'
+import { newHistoryId, type HistoryStore } from './history.js'
+import type { JobEvent, JobInput, JobKind, JobState, StartJobRequest, HistoryEntry } from './types.js'
+import { randomUUID } from 'node:crypto'
+
+export interface JobMeta {
+  /** stored input thumbnail id (points into the history store's inputs/). */
+  imageId?: string
+}
+
+interface JobRecord {
+  state: JobState
+  controller: AbortController
+}
+
+export class JobStore {
+  private readonly jobs = new Map<string, JobRecord>()
+  private readonly listeners = new Map<string, Set<(e: JobEvent) => void>>()
+
+  create(req: StartJobRequest, meta: JobMeta): JobState {
+    const now = new Date().toISOString()
+    const id = `job_${randomUUID().slice(0, 18)}`
+    const state: JobState = {
+      id,
+      kind: req.kind,
+      status: 'queued',
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.jobs.set(id, { state, controller: new AbortController() })
+    return state
+  }
+
+  get(id: string): JobState | undefined {
+    return this.jobs.get(id)?.state
+  }
+
+  abort(id: string): boolean {
+    const rec = this.jobs.get(id)
+    if (!rec) return false
+    rec.controller.abort()
+    return true
+  }
+
+  signal(id: string): AbortSignal | undefined {
+    return this.jobs.get(id)?.controller.signal
+  }
+
+  subscribe(id: string, cb: (e: JobEvent) => void): (() => void) | null {
+    if (!this.jobs.has(id)) return null
+    let set = this.listeners.get(id)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(id, set)
+    }
+    set.add(cb)
+    return () => {
+      set?.delete(cb)
+      if (set && set.size === 0) this.listeners.delete(id)
+    }
+  }
+
+  private emit(id: string, event: JobEvent): void {
+    const set = this.listeners.get(id)
+    if (!set) return
+    for (const cb of [...set]) {
+      try { cb(event) } catch { /* a bad subscriber must not strand the stream */ }
+    }
+  }
+
+  /** Update job state (public — the runner writes progress/status). */
+  update(id: string, patch: Partial<JobState>, event?: JobEvent): JobState {
+    const rec = this.jobs.get(id)
+    if (!rec) return patch as JobState
+    rec.state = { ...rec.state, ...patch, updatedAt: new Date().toISOString() }
+    if (event) this.emit(id, event)
+    return rec.state
+  }
+
+  /** Update + emit the canonical event for a terminal state. */
+  settle(id: string, patch: Partial<JobState>): JobState {
+    const state = this.update(id, patch)
+    const now = new Date().toISOString()
+    if (state.status === 'completed') this.emit(id, { type: 'completed', job: state, at: now })
+    else if (state.status === 'failed') this.emit(id, { type: 'failed', error: state.error ?? 'generation failed', result: state.result, at: now })
+    else if (state.status === 'cancelled') this.emit(id, { type: 'cancelled', at: now })
+    else if (state.status === 'needs_confirmation') {
+      this.emit(id, {
+        type: 'needs_confirmation',
+        dimensions: state.dimensions ?? {},
+        pkgType: state.pkgType ?? null,
+        fileName: state.fileName ?? null,
+        at: now,
+      })
+    }
+    return state
+  }
+
+  remove(id: string): void {
+    this.jobs.delete(id)
+    this.listeners.delete(id)
+  }
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && (err.name === 'AbortError' || /abort/i.test(err.message))
+}
+
+/** Map the tool-body `needs_auth` outcome to a job failure with the marker. */
+function isNeedsAuth(result: Record<string, unknown> | undefined): boolean {
+  return result?.status === 'needs_auth'
+}
+
+export interface RunOutcome {
+  state: JobState
+  /** whether a history entry was appended. */
+  recorded: boolean
+}
+
+/**
+ * Run one generation to a terminal state. Returns the final JobState.
+ * History recording happens here so entry and state cannot drift.
+ */
+export async function runGeneration(
+  store: JobStore,
+  backend: ComponentGenBackend,
+  history: HistoryStore,
+  id: string,
+  req: StartJobRequest,
+  meta: JobMeta,
+  onProgress?: (message: string) => void,
+): Promise<RunOutcome> {
+  if (!store.get(id)) return { state: { id, kind: req.kind, status: 'failed', error: 'job not found', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() }, recorded: false }
+  const signal = store.signal(id)
+
+  const progress = (message: string): void => {
+    store.update(id, { status: 'running', progress: message })
+    onProgress?.(message)
+  }
+  const exec = { signal }
+
+  try {
+    if (req.kind === 'symbol') {
+      progress('正在生成 Symbol…')
+      const result = await backend.generateSymbol(
+        { imageDataUrl: req.input.imageDataUrl ?? '', instruction: req.input.instruction },
+        exec,
+      )
+      if (isNeedsAuth(result)) return fail('needs_auth')
+      const state = store.settle(id, { status: 'completed', result })
+      await record(history, meta, req, state)
+      return { state, recorded: true }
+    }
+
+    if (req.kind === 'extract-footprint') {
+      progress('正在提取封装尺寸…')
+      const result = await backend.extractFootprint(
+        {
+          imageDataUrl: req.input.imageDataUrl ?? '',
+          packageType: req.input.packageType,
+          instruction: req.input.instruction,
+        },
+        exec,
+      )
+      if (isNeedsAuth(result)) return fail('needs_auth')
+      if (result.status === 'needs_confirmation') {
+        const dims = result.dimensions && typeof result.dimensions === 'object' ? result.dimensions : {}
+        const pkg = typeof result.pkgType === 'string' ? result.pkgType : (req.input.packageType ?? null)
+        const fileName = typeof result.fileName === 'string' ? result.fileName : null
+        const state = store.settle(id, {
+          status: 'needs_confirmation',
+          dimensions: dims as Record<string, unknown>,
+          pkgType: pkg,
+          fileName,
+        })
+        return { state, recorded: false }
+      }
+      if (result.status === 'cancelled') {
+        const state = store.settle(id, { status: 'cancelled', result })
+        await record(history, meta, req, state)
+        return { state, recorded: true }
+      }
+      const state = store.settle(id, { status: 'completed', result })
+      await record(history, meta, req, state)
+      return { state, recorded: true }
+    }
+
+    // generate-footprint
+    progress('正在生成封装…')
+    const result = await backend.generateFootprint(
+      {
+        packageType: req.input.packageType ?? '',
+        fileName: req.input.fileName,
+        dimensions: req.input.dimensions ?? {},
+      },
+      exec,
+    )
+    if (isNeedsAuth(result)) return fail('needs_auth')
+    if (result.status === 'cancelled') {
+      const state = store.settle(id, { status: 'cancelled', result })
+      await record(history, meta, req, state)
+      return { state, recorded: true }
+    }
+    const state = store.settle(id, { status: 'completed', result })
+    await record(history, meta, req, state)
+    return { state, recorded: true }
+  } catch (err) {
+    if (isAbortError(err)) {
+      const state = store.settle(id, { status: 'cancelled' })
+      await record(history, meta, req, state).catch(() => {})
+      return { state, recorded: true }
+    }
+    const message = String((err as Error)?.message || err)
+    const state = store.settle(id, { status: 'failed', error: message })
+    await record(history, meta, req, state).catch(() => {})
+    return { state, recorded: true }
+  }
+
+  function fail(kind: 'needs_auth'): { state: JobState; recorded: boolean } {
+    const state = store.settle(id, {
+      status: 'failed',
+      error: kind === 'needs_auth' ? 'Huaqiu EDA login required' : 'generation failed',
+      result: { status: kind },
+    })
+    void record(history, meta, req, state).catch(() => {})
+    return { state, recorded: true }
+  }
+}
+
+/** Build + append a history entry for a terminal job state. */
+async function record(
+  history: HistoryStore,
+  meta: JobMeta,
+  req: StartJobRequest,
+  state: JobState,
+): Promise<void> {
+  const kind: 'symbol' | 'footprint' = state.kind === 'symbol' ? 'symbol' : 'footprint'
+  const status: HistoryEntry['status'] = state.status === 'completed' ? 'generated' : state.status === 'cancelled' ? 'cancelled' : 'failed'
+  const result = state.result as Record<string, unknown> | undefined
+  const artifact = result?.artifact && typeof result.artifact === 'object'
+    ? result.artifact as { id?: unknown; filename?: unknown; size?: unknown }
+    : null
+  const entry: HistoryEntry = {
+    id: newHistoryId(),
+    kind,
+    createdAt: state.updatedAt ?? state.createdAt,
+    status,
+    input: {
+      ...(meta.imageId ? { imageId: meta.imageId } : {}),
+      ...(req.input.instruction ? { instruction: req.input.instruction } : {}),
+      ...(req.input.packageType ? { packageType: req.input.packageType } : {}),
+      ...(req.input.dimensions && Object.keys(req.input.dimensions).length > 0 ? { dimensions: req.input.dimensions } : {}),
+    },
+    ...(req.input.edited && Object.keys(req.input.edited).length > 0 ? { edited: req.input.edited } : {}),
+    ...(status === 'generated' && artifact?.id
+      ? {
+        result: {
+          artifactId: String(artifact.id),
+          filename: typeof artifact.filename === 'string' ? artifact.filename : (result?.filename as string | undefined) ?? `${kind}.kicad_${kind === 'symbol' ? 'sym' : 'mod'}`,
+          ...(typeof result?.fileUrl === 'string' ? { fileUrl: result.fileUrl } : {}),
+          ...(typeof artifact.size === 'number' ? { size: artifact.size } : {}),
+        },
+      }
+      : {}),
+    ...(status === 'failed' && state.error ? { error: state.error } : {}),
+  }
+  await history.append(entry)
+}