# 1. Clone this repo somewhere
git clone https://github.com/adom-inc/adom-bridge-<NAME>.git
cd adom-bridge-<NAME>

# 2. Install adom-desktop, then point it at this local manifest:
adom-desktop bridge_install '{"manifestUrl":"file:///path/to/adom-bridge-<NAME>/bridge.json"}'

# Note: file:// works only when manifestUrl is parsed by adom-desktop's CLI on the
# same machine that owns the bridge files. For Docker callers, push to a wiki staging
# area and use the wiki URL.

# 3. Run any verb the bridge defines:
adom-desktop <name>_<verb> '{"...":"..."}'

# 4. Run the SDK demo to verify install/list/invoke/uninstall lifecycle:
bash scripts/demo-thirdparty-bridge.sh  # in adom-desktop repo

# Contributing

This bridge is part of the [Adom Desktop](https://github.com/adom-inc/adom-desktop) bridge ecosystem. It lives in its own repo (split from the main monorepo in 2026-05) specifically so the community can fork and improve it without coordinating with Adom Desktop's release cycle.

## Two-way street

- **You can extend this bridge** — add support for a new app version, new verbs, new platforms — and PR it back here. We sync accepted PRs into adom-desktop's bundled copy on the next release.
- **You can fork it** if your changes diverge too much (e.g. private vendor SDK integration). The bridge.json schema is the contract; fork freely under MIT.

## How shipping works

1. **Develop locally.** Clone this repo, edit, test. The bridge runs alongside an installed [Adom Desktop](https://github.com/adom-inc/adom-desktop); use `adom-desktop bridge_install` with a local `file://` manifest URL to test your changes against a real GUI.
2. **Open a PR** against `main`. The CI in `.github/workflows/validate.yml` checks that `bridge.json` is valid + verb prefixes look right + the BRIDGE_VERSION was bumped vs. main.
3. **Maintainer reviews + merges.** No squash-merge — we preserve your authored commits.
4. **Maintainer tags + ships.** A tag `v<X.Y.Z>` triggers `release-bridge.sh` on a maintainer's box, which uploads the new zip + manifest to [the Adom Wiki](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges). Anyone running Adom Desktop v1.7.19+ picks it up within 4 hours or on the next `adom-desktop refresh_bridges`.

We DON'T auto-ship from GitHub Actions today. Reason: `release-bridge.sh` needs an Adom Wiki API token, and we keep that secret on maintainer machines rather than in GH Actions secrets. The community trust model around auto-publishing community PRs to a shared wiki space is part of a separate effort ("Chunk D" in adom-desktop's TODO.md) — comment on an issue if you want to help design that.

## Bridge.json schema

See [the SDK guide on the Adom Wiki](https://wiki-ufypy5dpx93o.adom.cloud/apps/adom-desktop-bridges) for the authoritative schema. Quick summary:

- `manifest_version: 1`
- `name` — must match the directory name in adom-desktop's `plugins/` (when bundled)
- `version` — semver, bumped on every PR that ships
- `spawn.port: 0` — **always use 0** as of Adom Desktop v1.8.31+. Adom Desktop picks an OS-assigned ephemeral port and passes it via `--port <N>` to your bridge process. Don't hardcode.
- `spawn.healthEndpoint: "/status"` — path-only (recommended). Adom Desktop builds the URL using the runtime port.
- `verbPrefixes: ["<name>_"]` — the CLI verb prefixes this bridge owns.

## Versioning

- **Patch** (`0.8.3 → 0.8.4`): bug fixes, hardening, no schema or behavior changes.
- **Minor** (`0.8 → 0.9`): new verbs, new optional manifest fields, backward-compatible behavior changes.
- **Major** (`0.x → 1.0`, `1.x → 2.0`): breaking changes to verb shapes or removal of verbs. Coordinate with adom-desktop maintainers before submitting — we may need to wait for a desktop-app release that handles both versions.

Bump `BRIDGE_VERSION` AND `bridge.json`'s `"version"` field in the same commit — they must match.

## Testing locally

```bash
# 1. Clone this repo somewhere
git clone https://github.com/adom-inc/adom-bridge-<NAME>.git
cd adom-bridge-<NAME>

# 2. Install adom-desktop, then point it at this local manifest:
adom-desktop bridge_install '{"manifestUrl":"file:///path/to/adom-bridge-<NAME>/bridge.json"}'

# Note: file:// works only when manifestUrl is parsed by adom-desktop's CLI on the
# same machine that owns the bridge files. For Docker callers, push to a wiki staging
# area and use the wiki URL.

# 3. Run any verb the bridge defines:
adom-desktop <name>_<verb> '{"...":"..."}'

# 4. Run the SDK demo to verify install/list/invoke/uninstall lifecycle:
bash scripts/demo-thirdparty-bridge.sh  # in adom-desktop repo
```

## Why this bridge lives in its own repo

When adom-desktop was a monorepo, all bridges shipped on adom-desktop's NSIS release cycle — meaning a community contributor couldn't release a KiCad fix without waiting for an adom-desktop maintainer to cut a new desktop installer. As of 2026-05 the bridges live in independent repos so:

- Community can release at their own cadence
- Adom Desktop's installer ships a "known-good" snapshot but auto-updates from the wiki for newer versions
- A maintainer outside Adom Industries can take over a bridge (e.g. a KiCad 11 expert maintains the KiCad bridge) without commit access to adom-desktop itself

See [adom-desktop TODO.md → Chunks C/D](https://github.com/adom-inc/adom-desktop/blob/main/TODO.md) for the broader design.

## Code of conduct

Be kind. We're building this for engineers who need their CAD tools to work with AI without giving up local control of their files. If your PR is rejected, we'll explain why — and you can fork.

## License

MIT — see [LICENSE](LICENSE).