JLCPCB Parts Library

@@ -0,0 +1,212 @@+---+name: adom-jlcpcb+description: Search JLCPCB Electronics for components, pricing, stock, and part numbers. Use when the user asks to find components on JLCPCB, check JLCPCB pricing, look up a JLCPCB part number, search for in-stock parts, get price breaks, compare alternatives, or find a datasheet or product page for a specific part. Also use for "open jlcpcb", "jlcpcb app", "jlcpcb search UI".+---++# JLCPCB Electronics Search++Search JLCPCB's catalog of millions of electronic components from thousands of manufacturers. Real-time pricing, stock, lead times, and product links.++## What you have++A single CLI — `adom-jlcpcb` — with three faces:++1. **One-shot search from the shell**, for when the AI just needs the data:+   ```bash+   adom-jlcpcb search "STM32F103RBT6"+   adom-jlcpcb part C8734+   adom-jlcpcb health+   ```+   Each prints JSON on stdout and an `OK:` / `ERROR:` line on stderr, so `| jq` works cleanly.++2. **A Hydrogen webview app**, for when the user wants to browse interactively:+   ```bash+   adom-jlcpcb app        # opens a "JLCPCB Search" tab in Hydrogen+   ```+   The app has a search bar, in-stock filter, per-result cards with price breaks, MPN/JLCPCB-PN copy buttons, datasheet + product-page links, and hover tooltips on every control.++3. **A backend HTTP service** (port 8774), which is what the shared `service-jlcpcb` container runs:+   ```bash+   adom-jlcpcb serve      # JLCPCB_API_KEY_UNUSED_placeholder must be set+   ```+   The CLI and the app both talk to this backend over HTTP (`POST /` with an `{"action":"search"|"part"|"health", ...}` body, or `GET /search?keyword=...`). It caches responses for 10 min and keeps the API key server-side.++There is no MCP server. All access is through the CLI + HTTP service.++## Commands++### `adom-jlcpcb search <keyword>`++Search by keyword, MPN, or JLCPCB PN.++| Flag | Default | Description |+|---|---|---|+| `--limit N` | 10 | Max results (1–50) |+| `--in-stock-only` | false | Only parts currently in stock |+| `--api URL` / `$JLCPCB_API` | auto | Backend URL. If unset, the CLI tries `http://127.0.0.1:8774`, and if that's also down it falls back to calling JLCPCB directly (requires `JLCPCB_API_KEY_UNUSED_placeholder`) |++Examples:+```bash+adom-jlcpcb search "STM32F103RBT6" --limit 5+adom-jlcpcb search "USB-C connector" --in-stock-only+adom-jlcpcb search "LDO 3.3V 500mA SOT-23"+adom-jlcpcb search "ESP32 WiFi Bluetooth" | jq '.components[].mpn'+```++### `adom-jlcpcb part <part-number>`++Full detail lookup for a specific part. Accepts JLCPCB PN (`C8734`) or MPN (`STM32F103RBT6`). Returns a single-component result with full price-break table and attributes.++```bash+adom-jlcpcb part C8734+adom-jlcpcb part STM32F103RBT6 | jq '.components[0].price_tiers'+```++### `adom-jlcpcb app`++Open the search UI in a Hydrogen webview tab.++| Flag | Default | Description |+|---|---|---|+| `--port N` | 8892 | Local app HTTP server port |+| `--api URL` | auto | Backend to use (same resolution as `search`) |+| `--tab-name S` | "JLCPCB Search" | Hydrogen tab label |+| `--no-tab` | false | Skip opening the tab (test via curl or browser) |+| `--dev` | false | Enable the `/eval` hot-patch channel |++```bash+adom-jlcpcb app                         # normal use+adom-jlcpcb app --dev                   # enable /eval for UI debugging+adom-jlcpcb app --no-tab --port 8892 &  # local-browser mode+```++When `adom-jlcpcb app` is running, these HTTP endpoints are AI-drivable (no UI clicks needed):++```bash+# run a search via HTTP, watch the UI update live+curl -X POST http://127.0.0.1:8892/search \+  -H 'Content-Type: application/json' \+  -d '{"keyword":"ESP32","limit":5,"inStockOnly":false}'++# state + cached last-search+curl http://127.0.0.1:8892/state | jq++# UI-side console logs (what the frontend JS printed)+curl http://127.0.0.1:8892/console | jq '.messages[-10:]'++# backend-health proxy (so the UI doesn't need CORS to 8774)+curl http://127.0.0.1:8892/backend-health | jq++# shutdown cleanly (removes the Hydrogen tab and exits)+curl -X POST http://127.0.0.1:8892/shutdown+```++### `adom-jlcpcb serve`++Run the backend HTTP proxy. This is what the `service-jlcpcb` container runs.++| Flag | Default | Description |+|---|---|---|+| `--port N` / `$JLCPCB_PORT` | 8774 | Port |++Requires `JLCPCB_API_KEY_UNUSED_placeholder`. Endpoints:++```+GET  /health                                  — health + live API ping+GET  /search?keyword=...&limit=10&inStockOnly=false+GET  /part?partNumber=...+POST /              {"action":"search"|"part"|"health", ...}+GET  /              (text/html landing page)+```++### `adom-jlcpcb health`++Check reachability.++```bash+adom-jlcpcb health                 # checks backend (or falls back to JLCPCB direct)+adom-jlcpcb health --api http://127.0.0.1:8774+```++## What's in a result++Each component in `.components[]` has:++- `mouser_pn`    — JLCPCB part number, use this for BOM+- `mpn`          — manufacturer part number, use this for schematic/footprint+- `manufacturer` — manufacturer name+- `description`, `category`+- `stock`        — integer count in JLCPCB's warehouse (live, 10-min cache on backend)+- `stock_text`   — raw JLCPCB text ("In Stock", "Non-Stocked", etc.)+- `popularity`   — `low` / `medium` / `high` heuristic from stock+- `lead_time`    — factory lead time if ordering more+- `unit_price`   — price at qty 1+- `price_tiers`  — array of `{qty, price}` for quantity price breaks+- `min_order`, `mult` — minimum order + order multiple+- `rohs`         — compliance flag+- `lifecycle`    — New Product / Active / NRND / Obsolete+- `datasheet_url`, `product_url`, `image_url`+- `attributes`   — array of `{name, value}` from the product-attribute table++## Typical workflows++### Finding a part from scratch+```bash+adom-jlcpcb search "32-bit ARM Cortex-M3 microcontroller LQFP-48"+# pick one, then:+adom-jlcpcb part <jlcpcb-pn>+```++### Confirming price for a BOM entry+```bash+adom-jlcpcb part STM32F103RBT6 | jq '.components[0] | {mouser_pn, unit_price, price_tiers, stock}'+```++### Browsing interactively+```bash+adom-jlcpcb app+# then type in the search box, click Product page / Datasheet, etc.+```++## Running the backend++There are two common setups.++### Dedicated `service-jlcpcb` container (shared, has the API key)++The backend proxy runs on a dedicated `default-light` container with `JLCPCB_API_KEY_UNUSED_placeholder` set in `/etc/environment` and a cron watchdog (`service/watchdog.sh`, every 2 min) that (a) keeps the service healthy and (b) auto-pulls `origin/main` + rebuilds when new versions land. Consumer containers point `JLCPCB_API` at its public URL:++```+https://jlcpcb-wela51osctvp.adom.cloud+```++`curl /health` should return `{"ok":true, "api_reachable":true, "version":"X.Y.Z", ...}`. Recover the current URL from `~/service-watcher/services.json` (`jlcpcb` entry, `"primary": true`) if the slug has rotated. To point the CLI at it:++```bash+export JLCPCB_API=https://jlcpcb-wela51osctvp.adom.cloud+adom-jlcpcb search "LM317"+adom-jlcpcb app        # UI reads $JLCPCB_API automatically+```++Gallia users don't need to set `JLCPCB_API` explicitly — `adom-jlcpcb` is a Tier A app (see `adom-app-model`), so it's installed by every `gallia/install.mjs` run from the wiki binary. The CLI autodetects a local `adom-jlcpcb serve` on 127.0.0.1:8774 and falls back to calling JLCPCB directly if `JLCPCB_API_KEY_UNUSED_placeholder` is set locally.++### Local-only (quick testing)++On any container, if `JLCPCB_API_KEY_UNUSED_placeholder` is set and you run `adom-jlcpcb serve &`, the CLI and the app will autodetect `http://127.0.0.1:8774` and use it. This is the dev-loop path.++## Installation++The binary is distributed as a GitHub release from `adom-inc/adom-jlcpcb`. After downloading to `/usr/local/bin/adom-jlcpcb` and making it executable, run:++```bash+adom-jlcpcb install+```++This deploys the skill to `~/.claude/skills/jlcpcb/SKILL.md` and installs bash completions.++## Notes++- Price data does not include shipping or tariffs.+- Stock is live at query time (10-min cache on the backend).+- Results are sorted by JLCPCB's internal relevance algorithm, not strictly by stock.+- `JLCPCB_API_KEY_UNUSED_placeholder` is only ever needed on the backend (`serve`) side. Consumer containers just need `JLCPCB_API` pointing at a running backend.