@helios-lang/contract-utils 0.3.21 → 0.3.23

package/README.md

@@ -1,2 +1,54 @@
 # contract-utils
 Convenience and type-safety utilities for using Helios validators from within Typescript
+
+## Helios CLI
+
+Requires Node.js 22 or newer. Install globally with npm:
+
+```sh
+npm install -g @helios-lang/contract-utils
+helios --help
+helios compile --format typescript --out-dir ./generated
+helios login
+```
+
+`helios compile` and `hl2ts` share the same compiler and options. Compilation searches the current directory for `.hl` files and does not require login. `helios compile --help` lists compiler options. The compiler peer dependency is restricted to the supported 0.16/0.17 series.
+
+`helios login` opens `https://helios-lang.io/console` with an expiring login request. Connect your wallet, create a project if you have no active projects, compare the code with your terminal, and click **Authorize CLI**. All active project API keys for that wallet are installed locally. The browser displays **You can now close this tab** only after the CLI confirms that the file was saved. Use `helios login --no-browser` to open the printed URL manually, including from another computer. Login expires after ten minutes; cancellation or failure leaves the existing file intact unless it was already saved and only the acknowledgment failed (reported explicitly).
+
+Credentials are stored in a versioned `debugger.json` file:
+
+| OS | Directory |
+| --- | --- |
+| Linux | `$XDG_CONFIG_HOME/helios`, or `~/.config/helios` |
+| macOS | `~/Library/Application Support/Helios` |
+| Windows | `%APPDATA%\Helios` |
+
+Set `HELIOS_CONFIG_HOME` to override the directory. Unix directories/files use modes 700/600. Windows uses a current-user-only ACL. The JSON has `{version:1,selected,profiles}`, where `selected` is a project ID and `profiles` maps project IDs to `{id,name,created_at,apiKey,wallet,endpoint}`. Names need not be unique. Re-running login refreshes that wallet's snapshot and removes revoked projects while preserving other wallets. It keeps the selected project when available and otherwise selects the oldest returned project. No signatures, browser session cookies, or temporary login tokens are persisted.
+
+API keys in this file are secrets: do not commit or share it. They authorize both capture uploads and reads for their project. Login never prints key values. The console's ordinary metadata endpoints do not return them; key recovery uses an explicitly approved, short-lived CLI request.
+
+For development, run `pnpm test`. `node scripts/check-global-cli.mjs` packs the package, installs it into an isolated npm global prefix, and checks executable discovery and equivalent compilation. The CLI portability workflow runs these checks on Windows, macOS, and Linux with Node 22 and 24. Publish the package only after the website and Worker with CLI-login support have been deployed.
+
+### Compile for a debugger project
+
+```sh
+helios login
+helios compile --project "My project" --out-dir ./generated
+# The compatibility command accepts the same option:
+hl2ts --project "My project" --out-dir ./generated
+```
+
+`--project` selects an exact configured project name and validates its key through `GET /v1/project` before writing output. Unknown names list all configured project names/IDs; an empty configuration explains how to run `helios login`. Duplicate names are rejected as ambiguous. Revoked keys, stale project metadata, and service outages stop compilation rather than generating a bundle with an unchecked key.
+
+Generated JS/TS exports `$debugger: {projectId,name,apiKey,endpoint,sources}` and attaches it to each loaded validator/module. `makeContractContextBuilder()` carries that context onto the UPLC programs used by each validator's `$hash.context.program`, including source maps and unoptimized companions. Binding happens after cache lookup: changing projects does not reuse another project's credentials, and compilation caches remain credential-free. Written contract artifacts also preserve the context. Script CBOR and hashes are unchanged.
+
+With the corresponding tx-utils release and ledger evaluation-observer support, `spendWithRedeemer()`, minting/staking methods, and attached programs automatically deliver failed builds to that project. No explicit `makeDebuggerService()` call is needed. `makeTxBuilder({isMainnet, debugger:false})` disables automatic capture; an explicit debugger service overrides bundle configuration. Unannotated bundles retain their existing behavior.
+
+The API key is intentionally embedded in generated bundles, including browser bundles, and grants upload **and read** access to that project's feed. Use project-specific keys appropriate for that distribution. The key is sent in the authorization header, not in capture payloads. Omitting `--project` embeds no debugger credentials.
+
+### Offline wallet generation
+
+`helios wallet create --network preprod` prints JSON containing a cryptographically random 24-word recovery phrase and its base address. It does not contact a service. Supported networks are `preprod` (default), `preview`, and `mainnet`.
+
+Use `helios wallet create --network preprod --out wallet.json` to write a new private file instead of printing the phrase. Existing files are never overwritten. The output phrase can be pasted into a demo’s ignored `.env.local` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -17,7 +17,8 @@
   ],
   "type": "module",
   "bin": {
-    "hl2ts": "src/hl2ts.js"
+    "hl2ts": "src/hl2ts.js",
+    "helios": "src/helios.mjs"
   },
   "author": "Christian Schmitz",
   "license": "BSD-3-Clause",
@@ -33,7 +34,7 @@
     "singleQuote": false
   },
   "peerDependencies": {
-    "@helios-lang/compiler": "*"
+    "@helios-lang/compiler": "^0.16.0 || ^0.17.0"
   },
   "dependencies": {
     "@helios-lang/cli-utils": "^0.1.10",
@@ -41,8 +42,13 @@
     "@helios-lang/compiler-utils": "^0.5.15",
     "@helios-lang/crypto": "0.2.3",
     "@helios-lang/ledger": "^0.7.8",
+    "@helios-lang/tx-utils": "^0.6.41",
     "@helios-lang/type-utils": "^0.3.0",
-    "@helios-lang/uplc": "^0.7.15"
+    "@helios-lang/uplc": "^0.7.15",
+    "open": "^10.2.0"
+  },
+  "engines": {
+    "node": ">=22"
   },
   "scripts": {
     "build": "pnpm run prettify && pnpm run build:types && pnpm run test:suite",

package/src/artifacts/ChildArtifactWriter.js

@@ -99,6 +99,24 @@ export class ChildArtifactWriter extends ArtifactWriter {
             throw new Error("unhandled Plutus version")
         }
 
+        const debuggerContext =
+            /** @type {UplcProgram & {$debugger?: import("../index.js").DebuggerContext}} */ (
+                program
+            ).$debugger
+        if (debuggerContext && includeDef) {
+            this.writeDefLine(
+                `export const $debugger = ${JSON.stringify(debuggerContext)}`
+            )
+            this.writeDeclLine(
+                `export declare const $debugger: import("@helios-lang/contract-utils").DebuggerContext`
+            )
+            this.writeDefLine(
+                `Object.defineProperty(${name}, "$debugger", {value:$debugger})`
+            )
+            this.writeDefLine(
+                `if (${name}.alt) Object.defineProperty(${name}.alt, "$debugger", {value:$debugger})`
+            )
+        }
         return this
     }
 }

package/src/artifacts/RootArtifact.js

@@ -43,6 +43,14 @@ export function writeContractContextArtifacts(context, options) {
         }
     }
 
+    if (context.$debugger) {
+        root.writeDefLine(
+            `export const $debugger = ${JSON.stringify(context.$debugger)}`
+        )
+        root.writeDeclLine(
+            `export declare const $debugger: import("@helios-lang/contract-utils").DebuggerContext`
+        )
+    }
     root.writeValidatorNameUtils(validatorNames)
     root.save()
 }

package/src/cli/compile.js

@@ -0,0 +1,211 @@
+import {
+    existsSync,
+    mkdirSync,
+    promises,
+    readFileSync,
+    writeFileSync
+} from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { Cli, EnumOpt, StringOpt } from "@helios-lang/cli-utils"
+import { makeLoadedScriptsWriter } from "../codegen/index.js"
+import { loadCompilerLib } from "../compiler/index.js"
+import { typeCheckFiles } from "../compiler/ops.js"
+
+/**
+ * @typedef {{
+ *   name: string
+ *   purpose: string
+ *   sourceCode: string
+ * }} SourceDetails
+ */
+
+/**
+ * @typedef {"javascript" | "typescript"} FormatKind
+ */
+
+const NAME = "hl2ts"
+
+/** @param {string[]} args */
+export async function compile(args) {
+    const projectIndex = args.indexOf("--project")
+    if (projectIndex >= 0 && !args[projectIndex + 1]?.trim())
+        throw new Error(
+            "--project requires a project name; run helios login to configure projects"
+        )
+    const cli = new Cli(NAME, {
+        minArgs: 0,
+        maxArgs: 0,
+        options: {
+            project: new StringOpt({
+                long: "--project",
+                description: "Debugger project name (from helios login)",
+                default: ""
+            }),
+            outDir: new StringOpt({
+                long: "--out-dir",
+                short: "-o",
+                default: () => process.cwd()
+            }),
+            format: new EnumOpt({
+                long: "--format",
+                short: "-f",
+                variants: /** @type {FormatKind[]} */ ([
+                    "javascript",
+                    "typescript"
+                ]),
+                default: () => {
+                    const path = findPackageJson()
+
+                    if (
+                        path &&
+                        existsSync(join(dirname(path), "tsconfig.json"))
+                    ) {
+                        return "typescript"
+                    } else {
+                        return "javascript"
+                    }
+                }
+            })
+        },
+        action: mainInternal
+    })
+
+    await cli.run(["node", "hl2ts", ...args])
+}
+
+/**
+ * @param {string[]} _args
+ * @param {{outDir: string, format: FormatKind, project: string}} options
+ * @returns {Promise<void>}
+ */
+async function mainInternal(_args, { outDir, format, project }) {
+    const debugProject = project
+        ? await (await import("./project.mjs")).resolveProject(project)
+        : undefined
+    const lib = loadCompilerLib()
+
+    const filePaths = await listFiles(process.cwd(), ".hl")
+    const files = readFiles(filePaths)
+
+    console.log(`${NAME} using Helios compiler v${lib.version}`)
+    console.log(`  Transpiling ${Object.keys(files).length} inputs:`)
+    filePaths.forEach((p) => console.log(`    ${p}`))
+
+    const { modules, validators } = typeCheckFiles(lib, files, (current, rel) =>
+        resolve(join(dirname(current), rel))
+    )
+
+    const sources = debugProject
+        ? {
+              ...files,
+              ...Object.fromEntries(
+                  [...Object.values(modules), ...Object.values(validators)].map(
+                      (m) => [m.name, m.sourceCode]
+                  )
+              )
+          }
+        : undefined
+    const [js, dts, ts] = makeLoadedScriptsWriter(
+        debugProject ? { ...debugProject, sources } : undefined
+    )
+        .writeModules(modules)
+        .writeValidators(validators)
+        .finalize()
+
+    if (format == "typescript") {
+        mkdirIfNotExists(resolve(outDir))
+        const tsPath = join(outDir, "index.ts")
+
+        writeFileSync(tsPath, ts)
+
+        console.log(`  Output:`)
+        console.log(`    ${tsPath}`)
+    } else {
+        const resolvedOutDir = resolve(outDir)
+
+        mkdirIfNotExists(resolvedOutDir)
+
+        const jsPath = join(resolvedOutDir, "index.js")
+        const dtsPath = join(resolvedOutDir, "index.d.ts")
+
+        writeFileSync(jsPath, js)
+        writeFileSync(dtsPath, dts)
+
+        console.log(`  Output:`)
+        console.log(`    ${jsPath}`)
+        console.log(`    ${dtsPath}`)
+    }
+}
+
+/**
+ * @param {string} dir
+ * @param {string} ext
+ * @returns {Promise<string[]>}
+ */
+async function listFiles(dir, ext) {
+    const entries = await promises.readdir(dir, { withFileTypes: true })
+
+    const files = await Promise.all(
+        entries.map((entry) => {
+            const res = resolve(dir, entry.name)
+
+            if (entry.isDirectory()) {
+                if (entry.name.endsWith("node_modules")) {
+                    return []
+                } else {
+                    return listFiles(res, ext)
+                }
+            } else {
+                return res
+            }
+        })
+    )
+
+    return files.flat().filter((name) => name.endsWith(ext))
+}
+
+/**
+ * @param {string[]} filePaths
+ * @returns {{[path: string]: string}}
+ */
+function readFiles(filePaths) {
+    return Object.fromEntries(
+        filePaths.map((f) => {
+            return [f, readFileSync(f).toString()]
+        })
+    )
+}
+
+/**
+ * @param {string} fileName
+ * @returns {string | undefined}
+ */
+function findPackageJson(fileName = "package.json") {
+    let dir = process.cwd()
+
+    let path = join(dir, fileName)
+    let found = existsSync(path)
+
+    while (!found) {
+        const parent = dirname(dir)
+        if (parent === dir) return undefined
+        dir = parent
+        path = join(dir, fileName)
+        found = existsSync(path)
+    }
+
+    if (found) {
+        return path
+    } else {
+        return undefined
+    }
+}
+
+/**
+ * @param {string} dir
+ */
+function mkdirIfNotExists(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true })
+    }
+}

package/src/cli/config.mjs

@@ -0,0 +1,158 @@
+import { homedir } from "node:os"
+import { join, dirname, win32, posix } from "node:path"
+import {
+    lstat,
+    mkdir,
+    readFile,
+    writeFile,
+    rename,
+    chmod,
+    unlink
+} from "node:fs/promises"
+import { randomUUID } from "node:crypto"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+const exec = promisify(execFile)
+export async function windowsAcl(path, directory, set = false) {
+    // Pass paths through the environment, never interpolate them into PowerShell.
+    const script = `
+$ErrorActionPreference = 'Stop'
+$path = $env:HELIOS_CONFIG_ACL_PATH
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+if (${set ? "$true" : "$false"}) {
+    $acl = New-Object System.Security.AccessControl.${directory ? "DirectorySecurity" : "FileSecurity"}
+    $acl.SetOwner($sid)
+    $acl.SetAccessRuleProtection($true, $false)
+    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule($sid, 'FullControl', '${directory ? "ContainerInherit, ObjectInherit" : "None"}', 'None', 'Allow')
+    $acl.AddAccessRule($rule)
+    Set-Acl -LiteralPath $path -AclObject $acl
+} else {
+    $acl = Get-Acl -LiteralPath $path
+    if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'Configuration must be owned by the current user' }
+    foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
+        if ($rule.AccessControlType -eq 'Allow' -and $rule.IdentityReference.Value -ne $sid.Value) { throw 'Configuration must be accessible only by the current user' }
+    }
+}`
+    await exec(
+        "powershell.exe",
+        [
+            "-NoProfile",
+            "-NonInteractive",
+            "-EncodedCommand",
+            Buffer.from(script, "utf16le").toString("base64")
+        ],
+        {
+            windowsHide: true,
+            env: { ...process.env, HELIOS_CONFIG_ACL_PATH: path }
+        }
+    )
+}
+export function configPath(
+    platform = process.platform,
+    env = process.env,
+    home = homedir()
+) {
+    const join = platform === "win32" ? win32.join : posix.join
+    const directory =
+        env.HELIOS_CONFIG_HOME ||
+        (platform === "win32"
+            ? join(env.APPDATA || join(home, "AppData", "Roaming"), "Helios")
+            : platform === "darwin"
+              ? join(home, "Library", "Application Support", "Helios")
+              : join(env.XDG_CONFIG_HOME || join(home, ".config"), "helios"))
+    return join(directory, "debugger.json")
+}
+async function inspect(path, directory = false) {
+    try {
+        const stat = await lstat(path)
+        if (
+            stat.isSymbolicLink() ||
+            !(directory ? stat.isDirectory() : stat.isFile())
+        )
+            throw new Error(`Unsafe configuration path: ${path}`)
+        if (
+            process.platform !== "win32" &&
+            (stat.mode & 0o077 || stat.uid !== process.getuid?.())
+        )
+            throw new Error(`Configuration must be owner-only: ${path}`)
+        if (process.platform === "win32") await windowsAcl(path, directory)
+        return true
+    } catch (error) {
+        if (error.code === "ENOENT") return false
+        throw error
+    }
+}
+export async function readConfig(path = configPath()) {
+    await inspect(dirname(path), true)
+    if (!(await inspect(path)))
+        return { version: 1, selected: null, profiles: {} }
+    const data = JSON.parse(await readFile(path, "utf8"))
+    if (
+        data.version !== 1 ||
+        !data.profiles ||
+        typeof data.profiles !== "object" ||
+        Array.isArray(data.profiles)
+    )
+        throw new Error("Unsupported or invalid Helios configuration")
+    return data
+}
+export async function installProjects(
+    wallet,
+    projects,
+    endpoint,
+    path = configPath()
+) {
+    if (
+        !/^[a-f0-9]{56}$/.test(wallet) ||
+        !Array.isArray(projects) ||
+        !projects.length
+    )
+        throw new Error("Invalid or empty project response")
+    const ids = new Set()
+    for (const p of projects) {
+        if (
+            !/^[a-f0-9-]{36}$/.test(p.id) ||
+            ids.has(p.id) ||
+            typeof p.name !== "string" ||
+            !p.name.trim() ||
+            !Number.isSafeInteger(p.created_at) ||
+            p.created_at < 0 ||
+            !/^hdbg_[a-f0-9]{64}$/.test(p.apiKey)
+        )
+            throw new Error("Invalid project response")
+        ids.add(p.id)
+    }
+    const data = await readConfig(path)
+    for (const [id, profile] of Object.entries(data.profiles))
+        if (profile.wallet === wallet && profile.endpoint === endpoint)
+            delete data.profiles[id]
+    for (const project of projects)
+        data.profiles[project.id] = { ...project, wallet, endpoint }
+    if (!data.profiles[data.selected])
+        data.selected = [...projects].sort(
+            (a, b) => a.created_at - b.created_at || a.id.localeCompare(b.id)
+        )[0].id
+    const dir = dirname(path)
+    const existed = await inspect(dir, true)
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+    if (!existed && process.platform === "win32")
+        await windowsAcl(dir, true, true)
+    await inspect(dir, true)
+    const temporary = join(dir, `.debugger-${randomUUID()}.tmp`)
+    try {
+        await writeFile(temporary, JSON.stringify(data, null, 2) + "\n", {
+            flag: "wx",
+            mode: 0o600
+        })
+        if (process.platform === "win32")
+            await windowsAcl(temporary, false, true)
+        else await chmod(temporary, 0o600)
+        await inspect(path)
+        await rename(temporary, path)
+    } finally {
+        await unlink(temporary).catch((error) => {
+            if (error.code !== "ENOENT") throw error
+        })
+    }
+    return path
+}

package/src/cli/login.mjs

@@ -0,0 +1,117 @@
+import { installProjects } from "./config.mjs"
+const sleep = (ms, signal) =>
+    new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer)
+            reject(signal.reason)
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort)
+            resolve()
+        }, ms)
+        signal.addEventListener("abort", onAbort, { once: true })
+        if (signal.aborted) onAbort()
+    })
+export async function login({
+    noBrowser = false,
+    endpoint = "https://debugger.helios-lang.io",
+    fetchImpl = fetch,
+    openBrowser,
+    save = installProjects,
+    log = console.log,
+    wait = sleep,
+    signal = AbortSignal.timeout(600000)
+} = {}) {
+    async function request(path, method = "GET", token) {
+        const response = await fetchImpl(endpoint + "/v1/" + path, {
+            method,
+            redirect: "error",
+            signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]),
+            headers: token ? { Authorization: `Bearer ${token}` } : {}
+        })
+        const data = await response.json()
+        if (!response.ok)
+            throw Object.assign(
+                new Error(data.error || `HTTP ${response.status}`),
+                { status: response.status }
+            )
+        return data
+    }
+    const flow = await request("cli/logins", "POST")
+    if (
+        !/^[a-f0-9-]{36}$/.test(flow.id) ||
+        !/^hcli_[a-f0-9]{64}$/.test(flow.token) ||
+        !/^[A-F0-9]{8}$/.test(flow.code) ||
+        !Number.isFinite(flow.expires)
+    )
+        throw new Error("Invalid login response")
+    const url = new URL(flow.verificationUri)
+    if (
+        url.origin !== "https://helios-lang.io" ||
+        url.pathname !== "/console" ||
+        url.searchParams.get("cli_login") !== flow.id
+    )
+        throw new Error("Invalid Console login URL")
+    log(
+        `Open ${url.href}\nVerify code: ${flow.code}\nConnect your wallet, then authorize the CLI.`
+    )
+    if (!noBrowser) {
+        try {
+            await (openBrowser ?? (await import("open")).default)(url.href)
+        } catch {
+            log("Could not open your browser. Open the URL above manually.")
+        }
+    }
+    let failures = 0
+    while (!signal.aborted && Date.now() / 1000 < flow.expires) {
+        let result
+        try {
+            result = await request(`cli/logins/${flow.id}`, "GET", flow.token)
+            failures = 0
+        } catch (error) {
+            if (
+                signal.aborted ||
+                (error.status && error.status < 500 && error.status !== 429) ||
+                ++failures > 5
+            )
+                throw error
+            await wait(Math.min(5000 * 2 ** failures, 30000), signal)
+            continue
+        }
+        if (result.state === "approved") {
+            const path = await save(result.wallet, result.projects, endpoint)
+            for (let attempt = 0; ; attempt++) {
+                try {
+                    await request(
+                        `cli/logins/${flow.id}/complete`,
+                        "POST",
+                        flow.token
+                    )
+                    break
+                } catch (error) {
+                    if (
+                        signal.aborted ||
+                        attempt === 4 ||
+                        (error.status &&
+                            error.status < 500 &&
+                            error.status !== 429)
+                    )
+                        throw new Error(
+                            `Keys saved to ${path}, but completion could not be confirmed. ${error.message}`
+                        )
+                    await wait(5000, signal)
+                }
+            }
+            log(`Installed ${result.projects.length} project(s) in ${path}:`)
+            for (const project of result.projects)
+                log(`  ${JSON.stringify(project.name)}`)
+            return
+        }
+        if (result.state === "cancelled")
+            throw new Error("Login cancelled in browser")
+        if (result.state !== "pending")
+            throw new Error("Login already completed; run helios login again")
+        await wait(5000, signal)
+    }
+    throw new Error("Login expired or cancelled; run helios login again")
+}

package/src/cli/project.mjs

@@ -0,0 +1,67 @@
+import { readConfig } from "./config.mjs"
+export async function resolveProject(
+    name,
+    { read = readConfig, fetchImpl = fetch } = {}
+) {
+    const config = await read()
+    const projects = Object.values(config.profiles)
+    const available = projects.length
+        ? "Configured projects: " +
+          projects.map((p) => `${JSON.stringify(p.name)} (${p.id})`).join(", ")
+        : "No projects are configured. Run `helios login` to connect your wallet and install project keys."
+    const matches = projects.filter((project) => project.name === name)
+    if (!matches.length)
+        throw new Error(
+            `Project ${JSON.stringify(name)} does not exist. ${available}`
+        )
+    if (matches.length > 1)
+        throw new Error(
+            `Project name ${JSON.stringify(name)} is ambiguous. Give projects distinct names before compiling. ${available}`
+        )
+    const project = matches[0]
+    if (!/^hdbg_[a-f0-9]{64}$/.test(project.apiKey))
+        throw new Error("Invalid configured API key. Run `helios login` again.")
+    const endpoint = new URL(project.endpoint)
+    if (
+        endpoint.protocol !== "https:" ||
+        endpoint.username ||
+        endpoint.password ||
+        endpoint.pathname !== "/" ||
+        endpoint.search ||
+        endpoint.hash
+    )
+        throw new Error(
+            "Project endpoint must be an HTTPS origin. Run `helios login` again."
+        )
+    let response
+    try {
+        response = await fetchImpl(`${endpoint.origin}/v1/project`, {
+            headers: { Authorization: `Bearer ${project.apiKey}` },
+            signal: AbortSignal.timeout(10000),
+            redirect: "error"
+        })
+    } catch {
+        throw new Error(
+            "Could not validate the project API key with the debugger service. Check your connection and try again."
+        )
+    }
+    if (response.status === 401)
+        throw new Error(
+            `The API key for ${JSON.stringify(name)} is invalid or revoked. Run \`helios login\` again.`
+        )
+    if (!response.ok)
+        throw new Error(
+            `Debugger project validation failed (HTTP ${response.status}). Try again later.`
+        )
+    const remote = await response.json()
+    if (remote.id !== project.id || remote.name !== project.name)
+        throw new Error(
+            "Configured project metadata is outdated. Run `helios login` again."
+        )
+    return {
+        projectId: remote.id,
+        name: remote.name,
+        apiKey: project.apiKey,
+        endpoint: endpoint.origin
+    }
+}