app

Adom Wiki CLI

Public Made by Adom

by adom

The Adom Wiki CLI: publish and install packages with verified signatures, cut releases, open PRs and discussions, and discover and administer the wiki, all from your terminal. Replaces adompkg.

cliwikipackagesdeveloper-tools
Overview Files Skills Discover Packages Releases Dependencies Issues5 Breadcrumbs Pull Requests Activity
Closed general

Cloud Libraries verb family (library list/create/add/export/activate)

Colby Knox · 1mo ago ·closed by Colby Knox

Cloud Libraries shipped to prod on the wiki today (docs/cloud-libraries.md in adom/wiki has the full contract). The CLI needs a verb family so agents and scripts can drive carts without the browser. Server routes are live and stable; hints ride every response, pass them through as usual.

Proposed verbs (mirror gh-style naming):

  • library list: GET /api/libraries. Columns: ref (lib_), name, active marker, items, updated.
  • library create [--accent ] [--description ]: POST /api/libraries. First library becomes active server-side; say so from the response.
  • library show : GET /api/libraries/. Items with resolved title/MPN/manufacturer and unresolved rows flagged.
  • library add ... : POST items, repeatable; page refs accept owner/slug, bare unambiguous slug, or pg_. Idempotent (existed:true rows reported, not errored).
  • library remove <item-id|page-ref>: DELETE item (resolve a page-ref to its item first).
  • library set [--name] [--accent] [--description] [--active]: PATCH. --active true is the exclusive switch.
  • library activate : sugar for set --active true.
  • library duplicate , library delete (confirm prompt; parts on the wiki are untouched, say so).
  • library availability : GET availability; table part x kicad/fusion/altium with reasons on no.
  • library export [--format kicad] [-o ]: POST export, print the report (included, skipped BY NAME with reasons, warnings, collision qualifications), then download the bundle (owner-gated route) to -o or ./.zip. Exit nonzero when included is 0.

Addressing: is the lib_ public id; also accept an exact library NAME when it resolves uniquely for the caller (names rename freely, so print the lib_ id back every time). Rate limits: library bucket 30/min, export 12/min; surface 429 hints verbatim.

Optional follow-up once the basics land: library install composing export + adom-bridge send_files + kicad_install_library_bundle (the composite bridge verb exists as of kicad-bridge 0.9.252, capture proof in 0.9.253) so a container-side agent can land a cart inside a desktop KiCad the way the web button does.

Known server hint codes: LIB_NOT_FOUND, LIB_CAP_REACHED, ITEM_CAP_REACHED, NOTHING_TO_UPDATE, LIB_EXPORT_PARTIAL. Uniform 404s across owners (no existence oracle), so never diagnose a 404 as 'exists but private'.

1 Reply

Colby Knox · 1mo ago

Shipped in adom-wiki 1.7.14 (5-platform gate, latest advanced), same-day with the wiki launch so the CLI never lagged the feature.

All eleven verbs, each live-proven on prod against a throwaway library on my account (created, exercised, deleted; the component page was untouched throughout, as the model promises):

  • list / create / show: create surfaces the server's add-parts hint; show renders items with resolved metadata.
  • add: name sugar resolved 'ztest-cli-lib' -> lib_r23a8ahw25 with the LIB_REF hint printing the id back (names rename freely, scripts should key on lib_), and adding the same part twice reported LIB_ITEMS_EXISTED rather than erroring.
  • availability: the part x kicad/fusion/altium matrix with per-format reasons rendered as served.
  • export: printed the report and downloaded the real bundle (37,210 bytes, sha256-verified against the report's digest before writing; a mismatch fails the command). Proper KiCad structure confirmed: .kicad_sym, .pretty/, 3dmodels/, lib-table fragments, REPORT.json. included: 0 exits nonzero; skipped parts warn LIB_EXPORT_PARTIAL and are named, never silent.
  • duplicate / activate: the copy carried its item; activate switched the active flag exclusively (verified in list: exactly one active).
  • remove: accepts an item id or a page ref (pg_ compared directly, owner/slug resolved through the page's public id).
  • set / delete: renamed the copy, then deleted it BY THE NEW NAME through the sugar; delete requires --confirm and the LIB_DELETED hint states pages are untouched and the newest survivor is promoted.

One server-shape note: the /api/libraries routes wrap their payload in their own { status, data } envelope (like /api/widgets); every field read unwraps it defensively so a future flattening changes nothing.

Hints and docs: LIB_REF, LIB_ACTIVE, LIB_DELETED, LIB_ITEMS_EXISTED, LIB_EXPORT_PARTIAL are CLI-origin; LIB_NOT_FOUND / LIB_CAP_REACHED / ITEM_CAP_REACHED / NOTHING_TO_UPDATE pass through; docs/hint-codes.md and the bundled skill carry the contract including the uniform-404 rule (never read one as 'exists but private') and both rate buckets.

The composite library install (export -> adom-bridge staging -> kicad_install_library_bundle) is split out as #39 with the bridge-lane gotchas and acceptance criteria: it needs a session with a connected desktop KiCad to verify honestly, which this container cannot do. Closing this one.

Log in to reply.