@holochain/hc-spin 0.600.0 → 0.700.0-dev.0

package/CHANGELOG.md

@@ -9,6 +9,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Changed
 ### Removed
 
+## 2026-01-13: v0.700.0-dev.0
+### Changed
+- Updated to holochain 0.7.0-dev.7
+
+## 2025-11-20: v0.600.0
+### Added
+- A new argument `--force-admin-ports` takes a comma-separated list of port numbers, to force generated conductors to use specific admin ports. [#50](https://github.com/holochain/hc-spin/pull/50)
+
 ## 2025-11-06: v0.600.0-rc.0
 
 ### Added

package/README.md

@@ -4,12 +4,12 @@ CLI to run Holochain apps in development mode.
 
 ## Installation
 
-To install the latest version compatible with **holochain 0.4.x**:
+To install the latest version compatible with **holochain 0.6.x**:
 
-⚠️ Requires `@holochain/client 0.18.0` or newer ⚠️
+⚠️ Requires `@holochain/client 0.20.0` or newer ⚠️
 
 ```sh
-npm install --save-dev @holochain/hc-spin@">=0.400.0 <0.500.0"
+npm install --save-dev @holochain/hc-spin@">=0.600.0 <0.700.0"
 ```
 
 To install the latest version compatible with **holochain 0.5.x**:
@@ -20,12 +20,12 @@ To install the latest version compatible with **holochain 0.5.x**:
 npm install --save-dev @holochain/hc-spin@">=0.500.0 <0.600.0"
 ```
 
-To install the latest version compatible with **holochain 0.6.x**:
+To install the latest version compatible with **holochain 0.4.x**:
 
-⚠️ Requires `@holochain/client 0.20.0` or newer ⚠️
+⚠️ Requires `@holochain/client 0.18.0` or newer ⚠️
 
 ```sh
-npm install --save-dev @holochain/hc-spin@">=0.600.0 <0.700.0"
+npm install --save-dev @holochain/hc-spin@">=0.400.0 <0.500.0"
 ```
 
 ## Usage (holochain 0.6)

package/dist/main/index.js

@@ -12432,6 +12432,18 @@ function validateCliArgs(cliArgs, cliOpts, appDataRootDir) {
   const appId = cliOpts.appId ? cliOpts.appId : path.parse(path.basename(cliArgs[0])).name;
   const holochainPath = cliOpts.holochainPath;
   const numAgents = cliOpts.numAgents ? cliOpts.numAgents : 2;
+  let forceAdminPorts;
+  if (cliOpts.forceAdminPorts !== void 0) {
+    forceAdminPorts = cliOpts.forceAdminPorts.split(",").map((portStr) => {
+      const portInt = parseInt(portStr);
+      if (Number.isNaN(portInt)) {
+        throw new Error(
+          `The --force-admin-ports must be a comma-separated list of valid port numbers, but got: ${cliOpts.forceAdminPorts}`
+        );
+      }
+      return portInt;
+    });
+  }
   return {
     appId,
     holochainPath,
@@ -12442,7 +12454,8 @@ function validateCliArgs(cliArgs, cliOpts, appDataRootDir) {
     singalingUrl: cliOpts.signalingUrl,
     bootstrapUrl: cliOpts.bootstrapUrl,
     happOrWebhappPath: isHapp ? { type: "happ", path: happOrWebhappPath } : { type: "webhapp", path: happOrWebhappPath },
-    openDevtools: cliOpts.openDevtools ? true : false
+    openDevtools: cliOpts.openDevtools ? true : false,
+    forceAdminPorts
   };
 }
 async function createHappWindow(uiSource, appId, agentNum, appPort, appAuthToken, appDataRootDir) {
@@ -12563,7 +12576,7 @@ function setLinkOpenHandlers(browserWindow) {
 }
 const rustUtils = require("@holochain/hc-spin-rust-utils");
 const cli = new commander.Command();
-cli.name("hc-spin").description("CLI to run Holochain apps during development.").version(`${"0.600.0"} (built for holochain ${"0.6.0"})`).argument(
+cli.name("hc-spin").description("CLI to run Holochain apps during development.").version(`${"0.700.0-dev.0"} (built for holochain ${"0.7.0-dev.7"})`).argument(
   "<path>",
   "Path to .webhapp or .happ file to launch. If a .happ file is passed, either a UI path must be specified via --ui-path or a port pointing to a localhost server via --ui-port"
 ).option(
@@ -12587,6 +12600,9 @@ cli.name("hc-spin").description("CLI to run Holochain apps during development.")
 ).option(
   "--signaling-url <url>",
   "Url of the signaling server to use. By default, hc spin spins up a local development signaling server for you but this argument allows you to specify a custom one."
+).option(
+  "--force-admin-ports <ports>",
+  "A comma-separated list of port numbers for the holochain conductors to bind to their admin interfaces. By default, hc spin picks any available ports."
 ).option("--open-devtools", "Automatically open the devtools on startup.");
 cli.parse();
 const rl = require("readline").createInterface({
@@ -12686,9 +12702,12 @@ async function startLocalServices() {
     });
   });
 }
-async function spawnSandboxes(nAgents, happPath, bootStrapUrl, signalUrl, appId, networkSeed, targetArcFactor) {
-  const generateArgs = [
-    "sandbox",
+async function spawnSandboxes(nAgents, happPath, bootStrapUrl, signalUrl, appId, networkSeed, targetArcFactor, forceAdminPorts) {
+  const generateArgs = ["sandbox"];
+  if (forceAdminPorts !== void 0 && forceAdminPorts.length > 0) {
+    generateArgs.push("--force-admin-ports", forceAdminPorts.join(","));
+  }
+  generateArgs.push(
     "--piped",
     "generate",
     "--num-sandboxes",
@@ -12696,7 +12715,7 @@ async function spawnSandboxes(nAgents, happPath, bootStrapUrl, signalUrl, appId,
     "--app-id",
     appId,
     "--run"
-  ];
+  );
   let appPorts = "";
   for (let i = 1; i <= nAgents; i++) {
     const appPort = await getPorts();
@@ -12748,7 +12767,7 @@ electron.app.whenReady().then(async () => {
   if (CLI_OPTS.happOrWebhappPath.type === "webhapp") {
     happTargetDir = path.join(DATA_ROOT_DIR, "apps", CLI_OPTS.appId);
     const uiTargetDir = path.join(happTargetDir, "ui");
-    await rustUtils.saveHappOrWebhapp(
+    await rustUtils.unpackAndSaveWebhapp(
       CLI_OPTS.happOrWebhappPath.path,
       CLI_OPTS.appId,
       uiTargetDir,
@@ -12763,7 +12782,8 @@ electron.app.whenReady().then(async () => {
     CLI_OPTS.singalingUrl ? CLI_OPTS.singalingUrl : signalingUrl,
     CLI_OPTS.appId,
     CLI_OPTS.networkSeed,
-    CLI_OPTS.targetArcFactor
+    CLI_OPTS.targetArcFactor,
+    CLI_OPTS.forceAdminPorts
   );
   const lairUrls = [];
   sandboxPaths.forEach((sandbox) => {

package/docs/DEVSETUP.md

@@ -25,3 +25,15 @@ yarn build
 ```bash
 yarn start <path to .webhapp file>
 ```
+
+## Upgrade hc-spin to a new holochain version
+
+0. Update the flake.nix file if necessary and run `nix flake update`.
+1. Upgrade the upstream `@holochain/hc-spin-rust-utils` package [in this repo](https://github.com/holochain/hc-spin-rust-utils), following the instructions in its README. This may involve manual testing of a locally built `@holochain/hc-spin-rust-utils` here in the hc-spin repo. In that case, make sure to have entered nix shell with `nix develop` before testing, such that the correct holochain binary is being used by hc-spin.
+2. Once the new `@holochain/hc-spin-rust-utils` package has been upgraded and released, update it accordingly in the `package.json` file.
+3. Update `@holochain/client` in the `package.json` file to the appropriate version.
+4. Check whether any code changes are necessary after updating the packages. Once the code has been adapted, test it with `yarn start <path to .webhapp file>`.
+5. If testing succeeds, update the `version` field in `package.json`.
+6. Make any changes as necessary to the README. The README is what is shown on npmjs.org as the package description so it should be up to date.
+7. Build the hc-spin binary with `yarn build`.
+8. And finally publish it with `npm publish`.

package/flake.lock

@@ -2,11 +2,11 @@
   "nodes": {
     "crane": {
       "locked": {
-        "lastModified": 1762189950,
-        "narHash": "sha256-aotggLUXjlDGqKWibGPQcMZJGgdr79S21ISrv1Wz6RI=",
+        "lastModified": 1763511871,
+        "narHash": "sha256-KKZWi+ij7oT0Ag8yC6MQkzfHGcytyjMJDD+47ZV1YNU=",
         "owner": "ipetkov",
         "repo": "crane",
-        "rev": "50700219af884287ad7c85507e2f163b23a027a9",
+        "rev": "099f9014bc8d0cd6e445470ea1df0fd691d5a548",
         "type": "github"
       },
       "original": {
@@ -20,11 +20,11 @@
         "nixpkgs-lib": "nixpkgs-lib"
       },
       "locked": {
-        "lastModified": 1762040540,
-        "narHash": "sha256-z5PlZ47j50VNF3R+IMS9LmzI5fYRGY/Z5O5tol1c9I4=",
+        "lastModified": 1762980239,
+        "narHash": "sha256-8oNVE8TrD19ulHinjaqONf9QWCKK+w4url56cdStMpM=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "0010412d62a25d959151790968765a70c436598b",
+        "rev": "52a2caecc898d0b46b2b905f058ccc5081f842da",
         "type": "github"
       },
       "original": {
@@ -33,36 +33,19 @@
         "type": "github"
       }
     },
-    "hc-launch": {
-      "flake": false,
-      "locked": {
-        "lastModified": 1752056054,
-        "narHash": "sha256-iLHhGQXrSfgAibzLSx+mdOQnnTzq4mrRXto7+a+MDLM=",
-        "owner": "holochain",
-        "repo": "hc-launch",
-        "rev": "612aa244ceb4d2136e5adbf181ff0cc123daff65",
-        "type": "github"
-      },
-      "original": {
-        "owner": "holochain",
-        "ref": "holochain-weekly",
-        "repo": "hc-launch",
-        "type": "github"
-      }
-    },
     "hc-scaffold": {
       "flake": false,
       "locked": {
-        "lastModified": 1760566803,
-        "narHash": "sha256-fWflEEb2JQyVHfGglbx6dCR6X+4ECGM9pbxQYrKSZtQ=",
+        "lastModified": 1764163563,
+        "narHash": "sha256-KigJ3h25yNJfeQunPm5QYFPtLSk6nU3IEEvZY8w01Vo=",
         "owner": "holochain",
         "repo": "scaffolding",
-        "rev": "751a16e98ddb35db5763cbf4b882a849b642e7e7",
+        "rev": "87e997a7361d4aa7c1bb96261483ebba50223bd0",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "0.600.0-dev.0",
+        "ref": "v0.600.1",
         "repo": "scaffolding",
         "type": "github"
       }
@@ -70,16 +53,16 @@
     "holochain": {
       "flake": false,
       "locked": {
-        "lastModified": 1762372467,
-        "narHash": "sha256-8LoKyzjkAoHOlJ0+8hUrwc0LTX7/2TdVODoLwMZMNVA=",
+        "lastModified": 1768178786,
+        "narHash": "sha256-JsYqXKZMkt4v0hd7dA3GCs8ELuLEoiectSY4Zw9pWJw=",
         "owner": "holochain",
         "repo": "holochain",
-        "rev": "90f56b5bf15b572cd9fdbd63d5a40a288143ff5f",
+        "rev": "6594a0ed6a038113bc55e0c1545310736189d88b",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "holochain-0.6.0-rc.0",
+        "ref": "holochain-0.7.0-dev.7",
         "repo": "holochain",
         "type": "github"
       }
@@ -88,7 +71,6 @@
       "inputs": {
         "crane": "crane",
         "flake-parts": "flake-parts",
-        "hc-launch": "hc-launch",
         "hc-scaffold": "hc-scaffold",
         "holochain": "holochain",
         "kitsune2": "kitsune2",
@@ -98,11 +80,11 @@
         "rust-overlay": "rust-overlay"
       },
       "locked": {
-        "lastModified": 1762431364,
-        "narHash": "sha256-769gbrsWU5SejCYcvoTPkVakU8nj5qYUw6cDlMRIgDs=",
+        "lastModified": 1768299200,
+        "narHash": "sha256-wg7yUc/n6iYf5/qgV2tosZimJu0iTLVZOouko95TuiM=",
         "owner": "holochain",
         "repo": "holonix",
-        "rev": "2682fec89ecb743c13453a65ee775147076f1919",
+        "rev": "70c034a9eedfd3d48450432f938b86dc11202361",
         "type": "github"
       },
       "original": {
@@ -115,16 +97,16 @@
     "kitsune2": {
       "flake": false,
       "locked": {
-        "lastModified": 1762303720,
-        "narHash": "sha256-tC2k+1kPxpVYRYJLWYXQPvFlUwgfF4cKoFKbkak0vxU=",
+        "lastModified": 1763403287,
+        "narHash": "sha256-dqQJMoDbcD0ekttrv5+8ph5Yf25EdXwKktsxNjV57Iw=",
         "owner": "holochain",
         "repo": "kitsune2",
-        "rev": "112099b30381ea0d23b8b3af21f5b5bb81ced6c5",
+        "rev": "22de6e42100aa960d05f5f30427a236ad922bd80",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "v0.3.0",
+        "ref": "v0.3.2",
         "repo": "kitsune2",
         "type": "github"
       }
@@ -148,11 +130,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1762233356,
-        "narHash": "sha256-cGS3lLTYusbEP/IJIWGgnkzIl+FA5xDvtiHyjalGr4k=",
+        "lastModified": 1763622513,
+        "narHash": "sha256-1jQnuyu82FpiSxowrF/iFK6Toh9BYprfDqfs4BB+19M=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "ca534a76c4afb2bdc07b681dbc11b453bab21af8",
+        "rev": "c58bc7f5459328e4afac201c5c4feb7c818d604b",
         "type": "github"
       },
       "original": {
@@ -215,11 +197,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1762396738,
-        "narHash": "sha256-BarSecuxtzp1boERdABLkkoxQTi6s/V33lJwUbWLrLY=",
+        "lastModified": 1763692705,
+        "narHash": "sha256-tCKCyMYU0Vy+ph/xswlNsYXXjnFVweWBV+ew/5FS9tA=",
         "owner": "oxalica",
         "repo": "rust-overlay",
-        "rev": "c63598992afd54d215d54f2b764adc0484c2b159",
+        "rev": "6fbf5d328dce1828d887b8ee7d44a785196a34e7",
         "type": "github"
       },
       "original": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@holochain/hc-spin",
-  "version": "0.600.0",
-  "holochainVersion": "0.6.0",
+  "version": "0.700.0-dev.0",
+  "holochainVersion": "0.7.0-dev.7",
   "description": "CLI to run Holochain apps during development.",
   "author": "matthme",
   "homepage": "https://developer.holochain.org",
@@ -36,7 +36,7 @@
     "@electron-toolkit/preload": "^3.0.0",
     "@electron-toolkit/utils": "^3.0.0",
     "@holochain/client": "^0.20.0",
-    "@holochain/hc-spin-rust-utils": "0.600.0",
+    "@holochain/hc-spin-rust-utils": "0.700.0-dev.0",
     "@msgpack/msgpack": "^2.8.0",
     "bufferutil": "4.0.8",
     "commander": "11.1.0",

package/src/main/index.ts

@@ -66,6 +66,10 @@ cli
     '--signaling-url <url>',
     'Url of the signaling server to use. By default, hc spin spins up a local development signaling server for you but this argument allows you to specify a custom one.',
   )
+  .option(
+    '--force-admin-ports <ports>',
+    'A comma-separated list of port numbers for the holochain conductors to bind to their admin interfaces. By default, hc spin picks any available ports.',
+  )
   .option('--open-devtools', 'Automatically open the devtools on startup.');
 
 cli.parse();
@@ -211,11 +215,17 @@ async function spawnSandboxes(
   appId: string,
   networkSeed?: string,
   targetArcFactor?: number,
+  forceAdminPorts?: number[],
 ): Promise<
   [childProcess.ChildProcessWithoutNullStreams, Array<string>, Record<number, PortsInfo>]
 > {
-  const generateArgs = [
-    'sandbox',
+  const generateArgs = ['sandbox'];
+
+  if (forceAdminPorts !== undefined && forceAdminPorts.length > 0) {
+    generateArgs.push('--force-admin-ports', forceAdminPorts.join(','));
+  }
+
+  generateArgs.push(
     '--piped',
     'generate',
     '--num-sandboxes',
@@ -223,7 +233,8 @@ async function spawnSandboxes(
     '--app-id',
     appId,
     '--run',
-  ];
+  );
+
   let appPorts = '';
   for (let i = 1; i <= nAgents; i++) {
     const appPort = await getPort();
@@ -294,7 +305,7 @@ app.whenReady().then(async () => {
   if (CLI_OPTS.happOrWebhappPath.type === 'webhapp') {
     happTargetDir = path.join(DATA_ROOT_DIR, 'apps', CLI_OPTS.appId);
     const uiTargetDir = path.join(happTargetDir, 'ui');
-    await rustUtils.saveHappOrWebhapp(
+    await rustUtils.unpackAndSaveWebhapp(
       CLI_OPTS.happOrWebhappPath.path,
       CLI_OPTS.appId,
       uiTargetDir,
@@ -312,6 +323,7 @@ app.whenReady().then(async () => {
     CLI_OPTS.appId,
     CLI_OPTS.networkSeed,
     CLI_OPTS.targetArcFactor,
+    CLI_OPTS.forceAdminPorts,
   );
 
   const lairUrls: string[] = [];

package/src/main/validateArgs.ts

@@ -14,6 +14,7 @@ export type CliOpts = {
   signalingUrl?: string;
   bootstrapUrl?: string;
   openDevtools?: boolean;
+  forceAdminPorts?: string;
 };
 
 export type CliOptsValidated = {
@@ -27,6 +28,7 @@ export type CliOptsValidated = {
   bootstrapUrl: string | undefined;
   happOrWebhappPath: HappOrWebhappPath;
   openDevtools: boolean;
+  forceAdminPorts: number[] | undefined;
 };
 
 export type HappOrWebhappPath = {
@@ -87,6 +89,20 @@ export function validateCliArgs(
   const holochainPath = cliOpts.holochainPath;
   const numAgents = cliOpts.numAgents ? cliOpts.numAgents : 2;
 
+  let forceAdminPorts: number[] | undefined;
+  if (cliOpts.forceAdminPorts !== undefined) {
+    forceAdminPorts = cliOpts.forceAdminPorts.split(',').map((portStr) => {
+      const portInt = parseInt(portStr);
+
+      if (Number.isNaN(portInt)) {
+        throw new Error(
+          `The --force-admin-ports must be a comma-separated list of valid port numbers, but got: ${cliOpts.forceAdminPorts}`,
+        );
+      }
+      return portInt;
+    });
+  }
+
   return {
     appId,
     holochainPath,
@@ -104,5 +120,6 @@ export function validateCliArgs(
       ? { type: 'happ', path: happOrWebhappPath }
       : { type: 'webhapp', path: happOrWebhappPath },
     openDevtools: cliOpts.openDevtools ? true : false,
+    forceAdminPorts,
   };
 }