@holochain/hc-spin 0.601.0 → 0.700.0-dev.1

package/.envrc

@@ -0,0 +1 @@
+use flake

package/CHANGELOG.md

@@ -4,29 +4,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## \[Unreleased\]
 
-## 2026-05-14: v0.601.0
-
-### Changed
-
-- Bumped to holochain 0.6.1
-
-## 2026-02-13: v0.600.3-rc.0
+## 2026-02-13: v0.700.0-dev.1
 
 ### Changed
 - Holochain is now run with the iroh transport. The argument `--signaling-url` has been replaced with `--relay-url`.
-### Removed
-- Removed CLI option `--transport` as holochain is run with `quic` iroh transport.
-
-## 2026-01-22: v0.600.2-rc.0
 
+## 2026-01-13: v0.700.0-dev.0
 ### Changed
-- Added a CLI option `--transport` to choose between `quic` and `webrtc`. `quic` is used in combination with the iroh transport in Holochain, `webrtc` with tx5. The default transport in Holochain is iroh, so the default for hc-spin is `quic`. If no transport option is passed in on the command line, `quic` is used.
+- Updated to holochain 0.7.0-dev.7
 
-## 2026-01-22: v0.600.1-rc.0
-
-### Changed
-
-- Bumped to holochain 0.6.1-rc.0
+## 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
 

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

@@ -12439,7 +12439,7 @@ function validateCliArgs(cliArgs, cliOpts, appDataRootDir) {
     networkSeed: cliOpts.networkSeed,
     targetArcFactor: cliOpts.targetArcFactor,
     uiSource: cliOpts.uiPath ? { type: "path", path: cliOpts.uiPath } : cliOpts.uiPort ? { type: "port", port: cliOpts.uiPort } : { type: "path", path: path.join(appDataRootDir, "apps", appId, "ui") },
-    singalingUrl: cliOpts.signalingUrl,
+    relayUrl: cliOpts.relayUrl,
     bootstrapUrl: cliOpts.bootstrapUrl,
     happOrWebhappPath: isHapp ? { type: "happ", path: happOrWebhappPath } : { type: "webhapp", path: happOrWebhappPath },
     openDevtools: cliOpts.openDevtools ? true : false
@@ -12563,7 +12563,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.600.2-rc.0"} (built for holochain ${"0.6.1-rc.0"})`).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(
@@ -12585,8 +12585,8 @@ cli.name("hc-spin").description("CLI to run Holochain apps during development.")
   "--ui-port <number>",
   "Port pointing to a localhost dev server that serves your UI assets."
 ).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."
+  "--relay-url <url>",
+  "Url of the relay server to use. By default, hc spin spins up a local development relay server for you but this argument allows you to specify a custom one."
 ).option("--open-devtools", "Automatically open the devtools on startup.");
 cli.parse();
 const rl = require("readline").createInterface({
@@ -12664,29 +12664,29 @@ async function startLocalServices() {
   const localServicesHandle = childProcess__namespace.spawn("kitsune2-bootstrap-srv");
   return new Promise((resolve) => {
     let bootStrapUrl;
-    let signalUrl;
+    let relayUrl;
     let bootstrapRunning = false;
-    let signalRunnig = false;
+    let relayRunning = false;
     localServicesHandle.stdout.pipe(split()).on("data", async (line) => {
       console.log(`[hc-spin] | [kitsune2-bootstrap-srv]: ${line}`);
       if (line.includes("#kitsune2_bootstrap_srv#listening#")) {
         const hostAndPort = line.split("#kitsune2_bootstrap_srv#listening#")[1].split("#")[0];
         bootStrapUrl = `http://${hostAndPort}`;
-        signalUrl = `ws://${hostAndPort}`;
+        relayUrl = `http://${hostAndPort}`;
       }
       if (line.includes("#kitsune2_bootstrap_srv#running#")) {
         bootstrapRunning = true;
-        signalRunnig = true;
+        relayRunning = true;
       }
-      if (bootstrapRunning && signalRunnig && bootStrapUrl && signalUrl)
-        resolve([bootStrapUrl, signalUrl]);
+      if (bootstrapRunning && relayRunning && bootStrapUrl && relayUrl)
+        resolve([bootStrapUrl, relayUrl]);
     });
     localServicesHandle.stderr.pipe(split()).on("data", async (line) => {
       console.log(`[hc-spin] | [hc run-local-services] ERROR: ${line}`);
     });
   });
 }
-async function spawnSandboxes(nAgents, happPath, bootStrapUrl, signalUrl, appId, networkSeed, targetArcFactor) {
+async function spawnSandboxes(nAgents, happPath, bootStrapUrl, relayUrl, appId, networkSeed, targetArcFactor) {
   const generateArgs = [
     "sandbox",
     "--piped",
@@ -12711,7 +12711,7 @@ async function spawnSandboxes(nAgents, happPath, bootStrapUrl, signalUrl, appId,
   if (targetArcFactor !== void 0) {
     generateArgs.push("--target-arc-factor", targetArcFactor.toString());
   }
-  generateArgs.push("--bootstrap", bootStrapUrl, "webrtc", signalUrl);
+  generateArgs.push("--bootstrap", bootStrapUrl, "quic", relayUrl);
   let readyConductors = 0;
   const portsInfo = {};
   const sandboxPaths = [];
@@ -12755,12 +12755,12 @@ electron.app.whenReady().then(async () => {
       happTargetDir
     );
   }
-  const [bootstrapUrl, signalingUrl] = await startLocalServices();
+  const [bootstrapUrl, relayUrl] = await startLocalServices();
   const [sandboxHandle, sandboxPaths, portsInfo] = await spawnSandboxes(
     CLI_OPTS.numAgents,
     happTargetDir ? happTargetDir : CLI_OPTS.happOrWebhappPath.path,
     CLI_OPTS.bootstrapUrl ? CLI_OPTS.bootstrapUrl : bootstrapUrl,
-    CLI_OPTS.singalingUrl ? CLI_OPTS.singalingUrl : signalingUrl,
+    CLI_OPTS.relayUrl ? CLI_OPTS.relayUrl : relayUrl,
     CLI_OPTS.appId,
     CLI_OPTS.networkSeed,
     CLI_OPTS.targetArcFactor

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": 1778106249,
-        "narHash": "sha256-cM/AuKy5tMhwOOQIbha8ZRRMHVfNf7cv2aljIw+qoCg=",
+        "lastModified": 1766194365,
+        "narHash": "sha256-4AFsUZ0kl6MXSm4BaQgItD0VGlEKR3iq7gIaL7TjBvc=",
         "owner": "ipetkov",
         "repo": "crane",
-        "rev": "6d015ea29630b7ad2402841386da2cb617a470a7",
+        "rev": "7d8ec2c71771937ab99790b45e6d9b93d15d9379",
         "type": "github"
       },
       "original": {
@@ -20,11 +20,11 @@
         "nixpkgs-lib": "nixpkgs-lib"
       },
       "locked": {
-        "lastModified": 1777988971,
-        "narHash": "sha256-qIoWPDs+0/8JecyYgE3gpKQxW/4bLW/gp45vow9ioCQ=",
+        "lastModified": 1765835352,
+        "narHash": "sha256-XswHlK/Qtjasvhd1nOa1e8MgZ8GS//jBoTqWtrS1Giw=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "0678d8986be1661af6bb555f3489f2fdfc31f6ff",
+        "rev": "a34fae9c08a15ad73f295041fec82323541400a9",
         "type": "github"
       },
       "original": {
@@ -36,16 +36,16 @@
     "hc-scaffold": {
       "flake": false,
       "locked": {
-        "lastModified": 1774456561,
-        "narHash": "sha256-CQ3HUE++iyLWJFK9wt2TeusmbuLavGxF8kxnv8mMsVw=",
+        "lastModified": 1764163563,
+        "narHash": "sha256-KigJ3h25yNJfeQunPm5QYFPtLSk6nU3IEEvZY8w01Vo=",
         "owner": "holochain",
         "repo": "scaffolding",
-        "rev": "3329e3c01572dc525ee95caa3d179dc659134572",
+        "rev": "87e997a7361d4aa7c1bb96261483ebba50223bd0",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "v0.600.3-rc.0",
+        "ref": "v0.600.1",
         "repo": "scaffolding",
         "type": "github"
       }
@@ -53,16 +53,16 @@
     "holochain": {
       "flake": false,
       "locked": {
-        "lastModified": 1778596880,
-        "narHash": "sha256-uUJZkeqBAZgXtDf0juCRpKOUO3yY1gWEKWGqatWcVjY=",
+        "lastModified": 1769992510,
+        "narHash": "sha256-hYq8p1BiPR+AdiOgeOPV+Gz+aTs2t5yu3V8lBGctBkE=",
         "owner": "holochain",
         "repo": "holochain",
-        "rev": "3bdeaccd1c54fa351e76f7347601dfbc061d5bd4",
+        "rev": "5194f7af4f71db22dd22dc37cf8c1e68d0b6d628",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "holochain-0.6.1",
+        "ref": "holochain-0.7.0-dev.10",
         "repo": "holochain",
         "type": "github"
       }
@@ -76,19 +76,20 @@
         "kitsune2": "kitsune2",
         "lair-keystore": "lair-keystore",
         "nixpkgs": "nixpkgs",
+        "playground": "playground",
         "rust-overlay": "rust-overlay"
       },
       "locked": {
-        "lastModified": 1778614884,
-        "narHash": "sha256-Kxgtrs15iA9D0f4Sj/rt/yVRYk+Ew8TxeQrmMdYO0Qg=",
+        "lastModified": 1770384077,
+        "narHash": "sha256-9llOslhUNN0VN1EM57NDB5AByRgztxChw3DaytgcGjU=",
         "owner": "holochain",
         "repo": "holonix",
-        "rev": "9931f18ccf9721fc5469fd3ae9d5bb118a6bac5a",
+        "rev": "b6587f0dbbb68de2d69d526e35a3efe7d311f2c4",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "main-0.6",
+        "ref": "main",
         "repo": "holonix",
         "type": "github"
       }
@@ -96,16 +97,16 @@
     "kitsune2": {
       "flake": false,
       "locked": {
-        "lastModified": 1778073766,
-        "narHash": "sha256-/hG+/9VlZiC1u/UASbIOH0oeiUmKlzqvur++CWSVAbQ=",
+        "lastModified": 1770115587,
+        "narHash": "sha256-bF/7ERAfd41zEfzoUBKKyxuQU3c0QUi2Fc8MpM+hnEs=",
         "owner": "holochain",
         "repo": "kitsune2",
-        "rev": "b33fa55606f8bd5020cffacf1ffae41f92d4d296",
+        "rev": "31b84100151a1eccaf7ed3e0037d27f77b5d7cdb",
         "type": "github"
       },
       "original": {
         "owner": "holochain",
-        "ref": "v0.4.1",
+        "ref": "main",
         "repo": "kitsune2",
         "type": "github"
       }
@@ -129,11 +130,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1778430510,
-        "narHash": "sha256-Ti+ZBvW6yrWWAg2szExVTwCd4qOJ3KlVr1tFHfyfi8Q=",
+        "lastModified": 1766201043,
+        "narHash": "sha256-eplAP+rorKKd0gNjV3rA6+0WMzb1X1i16F5m5pASnjA=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "8fd9daa3db09ced9700431c5b7ad0e8ba199b575",
+        "rev": "b3aad468604d3e488d627c0b43984eb60e75e782",
         "type": "github"
       },
       "original": {
@@ -145,11 +146,11 @@
     },
     "nixpkgs-lib": {
       "locked": {
-        "lastModified": 1777168982,
-        "narHash": "sha256-GOkGPcboWE9BmGCRMLX3worL4EMnsnG8MyKmXNeYuhQ=",
+        "lastModified": 1765674936,
+        "narHash": "sha256-k00uTP4JNfmejrCLJOwdObYC9jHRrr/5M/a/8L2EIdo=",
         "owner": "nix-community",
         "repo": "nixpkgs.lib",
-        "rev": "f5901329dade4a6ea039af1433fb087bd9c1fe14",
+        "rev": "2075416fcb47225d9b68ac469a5c4801a9c4dd85",
         "type": "github"
       },
       "original": {
@@ -158,6 +159,23 @@
         "type": "github"
       }
     },
+    "playground": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1756729856,
+        "narHash": "sha256-xJnIfcIyLRTXsf+N8OOMnqzRkx2gT/DSta7qCm8yU7Y=",
+        "owner": "darksoil-studio",
+        "repo": "holochain-playground",
+        "rev": "5e858641de8ac6113cfa6b47ea1350762a629a61",
+        "type": "github"
+      },
+      "original": {
+        "owner": "darksoil-studio",
+        "ref": "main",
+        "repo": "holochain-playground",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "flake-parts": [
@@ -179,11 +197,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1778555852,
-        "narHash": "sha256-55EmwooVAS4UpA0oWd5wilKPRqCiHD5BAej9QiNwheY=",
+        "lastModified": 1766371695,
+        "narHash": "sha256-W7CX9vy7H2Jj3E8NI4djHyF8iHSxKpb2c/7uNQ/vGFU=",
         "owner": "oxalica",
         "repo": "rust-overlay",
-        "rev": "f29b0f7a9f367e0056b716f8aa137cb41e784444",
+        "rev": "d81285ba8199b00dc31847258cae3c655b605e8c",
         "type": "github"
       },
       "original": {

package/flake.nix

@@ -2,7 +2,7 @@
   description = "Flake for Holochain app development";
 
   inputs = {
-    holonix.url = "github:holochain/holonix?ref=main-0.6";
+    holonix.url = "github:holochain/holonix?ref=main";
 
     nixpkgs.follows = "holonix/nixpkgs";
     flake-parts.follows = "holonix/flake-parts";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@holochain/hc-spin",
-  "version": "0.601.0",
-  "holochainVersion": "0.6.1",
+  "version": "0.700.0-dev.1",
+  "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.601.1",
+    "@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
     '--relay-url <url>',
     'Url of the relay server to use. By default, hc spin spins up a local development relay 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();
@@ -240,6 +251,7 @@ async function spawnSandboxes(
     generateArgs.push('--target-arc-factor', targetArcFactor.toString());
   }
   generateArgs.push('--bootstrap', bootStrapUrl, 'quic', relayUrl);
+  // console.log('GENERATE ARGS: ', generateArgs);
 
   let readyConductors = 0;
   const portsInfo: Record<number, PortsInfo> = {};
@@ -293,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,
@@ -311,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 = {
   relayUrl?: 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,
   };
 }