@vtechcom/hexcore 2.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to `hexcore`. Versions follow [semver](https://semver.org);
+pre-releases are published under the `beta` npm tag, never `latest`.
+
+## 2.0.0-beta.1 — 2026-08-08
+
+First release published to npm, as **`@vtechcom/hexcore`** — npm refused the
+bare `hexcore` as too similar to an existing `hex-core`. The scope is only in
+the install line; the command it puts on your PATH is `hexcore`.
+
+```bash
+npm i -g @vtechcom/hexcore@beta && hexcore
+```
+
+That gets you a running control-plane, a web UI on the same port, and a Hydra
+Head.
+
+Beta because the surface is new, not because it is untested: the head lifecycle
+has been exercised against real hydra-node containers throughout. What has *not*
+had wide exposure is this packaging — one global command, configured from a
+browser, on machines other than the two it was built on. Treat the API and the
+settings file as stable-ish and the CLI flags as still movable.
+
+### Added
+
+- **`hexcore` CLI.** One command runs the control-plane and serves the built web
+  UI from the same port. `init`, `config`, `doctor`, `reset` and `clean`
+  alongside it. Commands that only touch files never load the application, so
+  they still work when the server will not start — which is when you reach for
+  them.
+- **First-run setup in the browser.** An unconfigured installation prints a
+  setup link and the UI walks four questions. It replaces editing a 123-line
+  `.env`, which is where anyone who had not read the code stopped. `hexcore
+  init` asks the same questions in a terminal for machines with no browser
+  pointed at them.
+- **Layered configuration.** Environment variable, then `.env` in the working
+  directory, then `~/.hexcore/config.json`, then the defaults. `hexcore config`
+  and the Settings screen print each value **and the layer that supplied it** —
+  layered configuration does not fail by producing a wrong value, it fails by
+  producing one nobody can explain.
+- **Editable settings**, applied without a restart. Only settings that survive
+  that are offered: `PORT` and `STATE_DIR` are read once at boot, so they are
+  reported read-only rather than shown as fields that silently do nothing.
+- **Reset and clean, in three scopes.** `reset` forgets configuration and keeps
+  heads; `clean` deletes heads, containers and persistence but keeps keys;
+  `clean --all` deletes everything and is CLI-only, because it destroys the keys
+  behind funded addresses *and* the database serving the request.
+- **Node console.** A live WebSocket to any node of a running head, showing every
+  frame verbatim with what you sent interleaved, plus container CPU and memory
+  and copy-ready hydra-sdk / WebSocket / HTTP snippets built from that node's own
+  URL. Command templates load into an editor rather than firing on click;
+  `Close`, `SafeClose` and `Abort` confirm first, matched on the JSON about to be
+  sent so a hand-typed one is caught too.
+- **`hydra-node 2.3.x (arm64)` profile** (`aniadev9/hydra-node:2.3.0-arm64`),
+  recommended on macOS with Apple Silicon. See *Known limitations*.
+- **Edit a head that has not run**, and reset one that has. A head that failed to
+  start was previously stuck with whatever it was created with, and
+  delete-and-recreate throws away keys and any address already holding test ADA.
+- `GET /api/heads/:id/resources` — CPU and memory per node container, plus the
+  head total, which is the level the ~500 MB-per-node budget is stated at.
+
+### Changed
+
+- **`STATE_DIR` no longer defaults to `./.hexcore`.** It adopts a `.hexcore`
+  already in the working directory and otherwise uses `~/.hexcore`. The old
+  default was relative to wherever you happened to be, which for a global
+  command would have made `cd` look like every head had disappeared. Existing
+  installations keep their directory and need no migration.
+- Container resource sampling, `docker stats` semantics: CPU is a delta between
+  two samples and memory has the page cache subtracted, the same figures
+  `docker stats` prints. Both report *nothing* rather than a plausible number
+  when they cannot be measured.
+- The Settings screen is no longer read-only prose about `.env`.
+
+### Fixed
+
+- **`hexcore clean` deleted containers belonging to other Hexcore installations.**
+  It matched on `io.hexcore.managed`, which is true of every Hexcore on the
+  Docker daemon, and more than one is normal — a checkout plus a global install
+  share one daemon. Containers now carry `io.hexcore.install` and bulk deletes
+  filter on it. This destroyed a running head during development; it is fixed and
+  tested.
+- **The packaged tarball could not load its own configuration.** `zod` was
+  declared by both the package and its bundled `@hexcore/shared`; npm deduped the
+  pair and left `node_modules/zod` empty, so every command touching config died
+  while `--version` and `--help` kept working. Packing now installs the tarball
+  and runs a real command against it, and refuses to leave a broken one behind.
+- The UI broke when Docker was unreachable — a fatal preflight check, plus a
+  banner that rendered as a 600px-tall column. Docker being down is now a
+  degraded state, not a refusal to start.
+- An image pull failure reports the full reference you configured. Docker names
+  the repository and drops the tag, so one wrong character reported a repository
+  you had never heard of.
+
+### Licence
+
+Apache-2.0. `hydra-node` itself is a separate Apache-2.0 project
+([cardano-scaling/hydra](https://github.com/cardano-scaling/hydra)); Hexcore runs
+its published images and neither vendors nor modifies them.
+
+### Known limitations
+
+- **Upstream hydra-node images are amd64-only.** On Apple Silicon the official
+  2.2.0+ image runs under Rosetta, stalls inside a KZG warm-up before it installs
+  a tracer, and fails as a readiness timeout with nothing in the log. On arm64
+  Linux the daemon refuses it outright. Hexcore warns about this at the point of
+  choosing, and on macOS/arm64 recommends `aniadev9/hydra-node:2.3.0-arm64` — a
+  rebuild of the same source. **That is a community image on a personal Docker
+  Hub account, not one this project controls**, and it is offered because the
+  alternative on that platform is 2.1.x, which carries a double-spend defect. It
+  is reproducible: rebuild 2.3.0 yourself, push it as `you/hydra-node:2.3.0-arm64`
+  and it resolves to the same profile with the same flags. This will be replaced
+  the moment the Hydra core team publishes multi-arch images.
+  ([#7](https://github.com/Vtechcom/hexcore-v2/issues/7))
+- **Container names collide between two installations on one Docker daemon.**
+  Names derive from `(headId, nodeIndex)` and head ids start at 1 everywhere, so
+  starting head 1 in one installation removes head 1's containers in another.
+  ([#6](https://github.com/Vtechcom/hexcore-v2/issues/6))
+- **The node console cannot reach a node when Hexcore is served over HTTPS.**
+  The browser dials the node directly and browsers block `ws://` from a secure
+  page. The panel predicts this and says so rather than failing opaquely.
+  ([#5](https://github.com/Vtechcom/hexcore-v2/issues/5))
+- No migration tool. The SQLite schema is idempotent and columns are only ever
+  added.
+- The admin token lives in `localStorage`. Acceptable for a self-hosted operator
+  tool; revisit before any internet-exposed or multi-tenant deployment.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Vtechcom
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,283 @@
+# Hexcore v2
+
+Monorepo for booting and operating **Hydra Heads** on Cardano — control-plane and
+web UI in one repository.
+
+> v2 is a rewrite of [hydra-hexcore](../hydra-hexcore) focused on one thing:
+> going from `git clone` to a running Hydra Head without a checklist.
+
+---
+
+## What changed from v1
+
+| | v1 | v2 |
+|---|---|---|
+| **Repos** | 3 separate (`hydra-hexcore`, `hexcore-ui`, `hexcore-cli`) | 1 monorepo |
+| **Key material** | You generated Hydra + Cardano keys yourself and POSTed them in | Generated server-side on head creation |
+| **Database** | MySQL + Redis, provisioned before first run | Embedded SQLite in the state dir |
+| **Config** | ~30 env vars, unvalidated | zod-validated, works with a single key set |
+| **Setup failures** | Surfaced as stack traces at random later points | `pnpm doctor` checks everything up front |
+| **Container names** | Derived from DB ids (`hexcore-hydra-node-7`) | Deterministic (`hexcore-h1-n0`) |
+| **Ports** | Scan upward from 10005 until free | Deterministic block per head |
+| **Failed boot** | Left orphaned containers behind | Rolls back every container it created |
+| **Head state** | Only "is the container up?" | Real Hydra state probed over WebSocket |
+| **Types** | Duplicated between API and UI | Single zod schema in `packages/shared` |
+
+---
+
+## Requirements
+
+- **Node** >= 22
+- **Docker** running and reachable by your user
+- Nothing else. The `offline` backend runs a real multi-node Hydra Head with no
+  chain, no credential and no waiting — a Blockfrost project id (free,
+  <https://blockfrost.io>) or a synced `cardano-node` socket is only needed when
+  you want heads on the real chain.
+
+No MySQL. No Redis. No RabbitMQ.
+
+---
+
+## Quick start
+
+```bash
+npm install -g @vtechcom/hexcore@beta
+hexcore
+```
+
+> **This is a beta**, published under the `beta` tag rather than `latest` — so
+> `npm i -g @vtechcom/hexcore` without `@beta` will not resolve until 2.0.0 is final.
+> The package is scoped; the command it installs is plain `hexcore`.
+> See [CHANGELOG.md](CHANGELOG.md) for what that means and what is known broken.
+
+Building it from this checkout gives the identical artefact:
+
+```bash
+pnpm install
+node scripts/pack-cli.mjs        # builds, packs, and verifies the tarball installs
+npm i -g ./vtechcom-hexcore-2.0.0-beta.1.tgz
+```
+
+That starts the control-plane and serves the web UI from the same port, and
+prints a setup link with a one-time token in it:
+
+```
+Hexcore is not configured yet. Open this link to finish setup:
+  http://localhost:4000/setup?token=…
+```
+
+Open it, answer four questions, and you have a working installation. Nothing to
+edit by hand; there is no `.env` to copy.
+
+> The token is not ceremony. Setup has to be reachable without a login, because
+> it is where the login is created — so on any interface but loopback, whoever
+> reaches the port first would otherwise choose the admin password.
+
+Prefer a terminal, or setting up a machine with no browser pointed at it?
+
+```bash
+hexcore init      # the same questions, in the shell
+```
+
+### Everything the CLI does
+
+```bash
+hexcore                 # start the control-plane and the web UI
+hexcore init            # configure from the terminal
+hexcore config          # every setting, and which layer it came from
+hexcore doctor          # check Docker, chain access and permissions
+hexcore reset           # forget the configuration; heads and keys are kept
+hexcore clean           # delete every head and its containers; keys are kept
+hexcore clean --all     # delete everything, including keys
+```
+
+### Where configuration comes from
+
+Four layers, highest wins:
+
+1. a real environment variable — for containers and CI
+2. a `.env` in the current directory
+3. `~/.hexcore/config.json`, written by the setup wizard or `hexcore init`
+4. the built-in defaults
+
+`hexcore config` prints the value **and the layer that supplied it**, which is
+the only useful answer to "I changed that setting and nothing happened".
+
+### From a checkout
+
+```bash
+pnpm install
+pnpm build
+pnpm start
+```
+
+Same first-run experience — the setup link is printed on boot. `pnpm doctor`
+runs the preflight checks on their own.
+
+### On Apple Silicon, read this before creating a head
+
+Every hydra-node image the Hydra core team publishes is **amd64-only**. On a Mac
+with an M-series chip the 2.2.0+ image runs under Rosetta, stalls inside a
+cryptographic warm-up *before* it installs a logger, and fails as a plain
+readiness timeout with nothing in the log to explain it.
+
+Hexcore warns about this while you are still choosing, and on macOS/arm64 it
+recommends `aniadev9/hydra-node:2.3.0-arm64` — the same 2.3.0 source rebuilt for
+arm64, which starts natively in 0.47s.
+
+**That is a community image on a personal Docker Hub account, not one this
+project controls.** It is offered because the only upstream image that boots
+there is 2.1.x, which carries a double-spend defect. If you would rather not
+depend on someone else's registry, rebuild 2.3.0 yourself and push it as
+`you/hydra-node:2.3.0-arm64` — it resolves to the same profile, with the same
+flags and the same warnings. This recommendation goes away the moment upstream
+publishes multi-arch images ([#7](https://github.com/Vtechcom/hexcore-v2/issues/7)).
+
+### Create and start a head
+
+```bash
+TOKEN=$(curl -s -X POST localhost:4000/api/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"admin","password":"<your password>"}' | jq -r .data.token)
+
+# Creates the head AND generates every key it needs.
+curl -X POST localhost:4000/api/heads \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"name":"my-head","nodeCount":3}'
+```
+
+The response contains one `cardanoAddress` per node. **Fund each of them with
+test ADA** (https://docs.cardano.org/cardano-testnets/tools/faucet) — a Hydra
+node cannot commit without UTxOs.
+
+```bash
+curl -X POST localhost:4000/api/heads/1/start  -H "Authorization: Bearer $TOKEN"
+curl     localhost:4000/api/heads/1/status     -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+## Layout
+
+```
+apps/
+  control-plane/        NestJS + Fastify adapter
+    src/
+      config.ts         zod-validated environment
+      preflight.ts      startup checks (also `pnpm doctor`)
+      hydra/keys.ts     Hydra + Cardano key generation
+      hydra/head.service.ts   head lifecycle: create/start/stop/reset
+      hydra/ws-client.ts      live Hydra state over WebSocket
+      docker/           container orchestration + rollback
+      db/               SQLite schema and repositories
+      controllers/      REST API (Swagger annotated)
+  web/                  Nuxt SPA (ssr:false) — Tailwind v4 + shadcn-vue
+
+packages/
+  shared/               zod schemas + types used by BOTH sides
+
+docs/                   UI specification and architecture notes
+sketches/               HTML mockups the UI design was chosen from
+```
+
+### Web UI
+
+Built, and served by the control-plane on the same port when `SERVE_WEB=true` —
+which is what `hexcore` does. It builds to static files (`nuxt generate`), so
+there is no second process and no second port.
+
+- [`docs/UI_SPEC.md`](docs/UI_SPEC.md) — screens, states, actions, error handling
+- [`docs/UI_ARCHITECTURE.md`](docs/UI_ARCHITECTURE.md) — stack and implementation notes
+
+### State directory
+
+Everything mutable lives under `STATE_DIR`. Unset, that is `~/.hexcore` — unless
+a `.hexcore` already exists in the working directory, which is adopted instead so
+an existing checkout keeps the heads and keys it already has.
+
+```
+~/.hexcore/
+  config.json                   settings from the wizard (0600)
+  hexcore.db                    SQLite
+  secrets.json                  jwt secret + admin password hash (0600)
+  install-id                    distinguishes this installation's containers
+  heads/head-1/
+    keys/n0.hydra.sk            0600, text-envelope format
+    keys/n0.cardano.sk
+    persistence/n0/             hydra-node state
+    protocol-parameters.json
+```
+
+`hexcore config` prints the resolved path. **Back this up to preserve funded
+addresses** — the Cardano signing keys exist here and nowhere else. `hexcore
+clean --all` deletes it, which is why that one is CLI-only and asks you to type
+your machine's name.
+
+---
+
+## API
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/health` | Liveness + Docker reachability (public) |
+| `POST` | `/api/auth/login` | Get a bearer token (public) |
+| `GET` | `/api/heads` | List heads with their nodes |
+| `POST` | `/api/heads` | Create a head, generating all keys |
+| `GET` | `/api/heads/:id` | Head detail |
+| `PATCH` | `/api/heads/:id` | Update settings (applied on next start) |
+| `POST` | `/api/heads/:id/start` | Boot every node, wait until ready |
+| `POST` | `/api/heads/:id/stop` | Remove containers, keep keys + state |
+| `POST` | `/api/heads/:id/restart` | Stop then start |
+| `POST` | `/api/heads/:id/reset` | Wipe persistence (`includeKeys` for keys too) |
+| `DELETE` | `/api/heads/:id` | Delete head, containers and state |
+| `GET` | `/api/heads/:id/status` | Live state probed from the nodes |
+| `GET` | `/api/heads/:id/nodes/:index/logs` | Tail a node's container log |
+| `GET` | `/api/heads/:id/events` | Lifecycle audit trail |
+
+Every response is `{ ok: true, data }` or `{ ok: false, error: { code, message } }`.
+
+---
+
+## Troubleshooting
+
+Run `pnpm doctor` first — it diagnoses most problems with a concrete fix.
+
+**`DOCKER_UNAVAILABLE`** — Docker is not running, or your user cannot use the
+socket. On Linux: `sudo usermod -aG docker $USER`, then log out and back in.
+
+**`CHAIN_PROVIDER_ERROR` / Blockfrost 403** — the key does not match
+`CARDANO_NETWORK`. A key starting with `preprod` only works on preprod.
+
+**Node never becomes ready** — check its log:
+`GET /api/heads/:id/nodes/0/logs`. The usual cause is an unfunded Cardano
+address; the head cannot proceed without UTxOs at each node's address.
+
+**Port already in use** — change `PORT_BASE`; each node needs 10 ports.
+
+---
+
+## Development
+
+```bash
+pnpm dev            # control-plane + web in watch mode
+pnpm dev:api        # control-plane only
+pnpm test           # unit tests
+pnpm doctor         # environment diagnostics
+```
+
+---
+
+## Licence
+
+[Apache License 2.0](LICENSE). Use it, ship it, fork it, build a product on it —
+the licence also grants you a patent licence from the contributors, which is the
+main reason to prefer it over MIT for infrastructure.
+
+Two things it does **not** cover, because they are not ours to license:
+
+- **hydra-node** is a separate project ([cardano-scaling/hydra](https://github.com/cardano-scaling/hydra), Apache-2.0).
+  Hexcore runs its published container images; it does not vendor or modify them.
+- `aniadev9/hydra-node:2.3.0-arm64`, the community rebuild recommended on Apple
+  Silicon, is a third-party image on a personal Docker Hub account. It is a
+  rebuild of upstream's Apache-2.0 source, but this project does not control that
+  registry — see the Apple Silicon section above.

package/dist/app.module.js

@@ -0,0 +1,55 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const config_module_1 = require("./config.module");
+const database_module_1 = require("./db/database.module");
+const auth_1 = require("./auth");
+const docker_service_1 = require("./docker/docker.service");
+const head_service_1 = require("./hydra/head.service");
+const capabilities_1 = require("./hydra/capabilities");
+const node_monitor_service_1 = require("./hydra/node-monitor.service");
+const boot_progress_1 = require("./hydra/boot-progress");
+const setup_service_1 = require("./setup.service");
+const heads_controller_1 = require("./controllers/heads.controller");
+const system_controller_1 = require("./controllers/system.controller");
+const cardano_controller_1 = require("./controllers/cardano.controller");
+const setup_controller_1 = require("./controllers/setup.controller");
+const auth_guard_1 = require("./common/auth.guard");
+const http_1 = require("./common/http");
+/**
+ * The whole control-plane is four modules deep on purpose. v1 grew to a dozen
+ * feature modules (hydra-main, hydra-heads, hydra-hub, monitoring-agent,
+ * rabbitmq, event-listener, blockfrost, axios, docker...) with circular
+ * dependencies between several of them; v2 keeps one service per concern.
+ */
+let AppModule = class AppModule {
+};
+exports.AppModule = AppModule;
+exports.AppModule = AppModule = __decorate([
+    (0, common_1.Module)({
+        imports: [config_module_1.ConfigModule, database_module_1.DatabaseModule],
+        controllers: [system_controller_1.SystemController, setup_controller_1.SetupController, heads_controller_1.HeadsController, cardano_controller_1.CardanoController],
+        providers: [
+            auth_1.AuthService,
+            docker_service_1.DockerService,
+            head_service_1.HeadService,
+            setup_service_1.SetupService,
+            capabilities_1.NodeCapabilitiesService,
+            node_monitor_service_1.NodeMonitorService,
+            boot_progress_1.BootTracker,
+            // Secure-by-default: every route needs a token unless marked @Public().
+            { provide: core_1.APP_GUARD, useClass: auth_guard_1.AuthGuard },
+            { provide: core_1.APP_INTERCEPTOR, useClass: http_1.ResponseEnvelopeInterceptor },
+            { provide: core_1.APP_FILTER, useClass: http_1.ApiExceptionFilter },
+        ],
+    })
+], AppModule);
+//# sourceMappingURL=app.module.js.map

package/dist/app.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,uCAAsE;AACtE,mDAA+C;AAC/C,0DAAsD;AACtD,iCAAqC;AACrC,4DAAwD;AACxD,uDAAmD;AACnD,uDAA+D;AAC/D,uEAAkE;AAClE,yDAAoD;AACpD,mDAA+C;AAC/C,qEAAiE;AACjE,uEAAmE;AACnE,yEAAqE;AACrE,qEAAiE;AACjE,oDAAgD;AAChD,wCAAgF;AAEhF;;;;;GAKG;AAkBI,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAjBrB,IAAA,eAAM,EAAC;QACJ,OAAO,EAAE,CAAC,4BAAY,EAAE,gCAAc,CAAC;QACvC,WAAW,EAAE,CAAC,oCAAgB,EAAE,kCAAe,EAAE,kCAAe,EAAE,sCAAiB,CAAC;QACpF,SAAS,EAAE;YACP,kBAAW;YACX,8BAAa;YACb,0BAAW;YACX,4BAAY;YACZ,sCAAuB;YACvB,yCAAkB;YAClB,2BAAW;YACX,wEAAwE;YACxE,EAAE,OAAO,EAAE,gBAAS,EAAE,QAAQ,EAAE,sBAAS,EAAE;YAC3C,EAAE,OAAO,EAAE,sBAAe,EAAE,QAAQ,EAAE,kCAA2B,EAAE;YACnE,EAAE,OAAO,EAAE,iBAAU,EAAE,QAAQ,EAAE,yBAAkB,EAAE;SACxD;KACJ,CAAC;GACW,SAAS,CAAG"}