@helios-lang/contract-utils 0.3.23 → 0.3.24

package/README.md

@@ -26,7 +26,16 @@ Credentials are stored in a versioned `debugger.json` file:
 
 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.
+Project API keys can be shared with collaborators. They authorize capture uploads and reads for their project. The project page in the Console always displays its key in a yellow box.
+
+To import a key from another project owner without wallet login:
+
+```sh
+helios import-key hdbg_<key-from-project-page>
+helios compile --project "Shared project" --help
+```
+
+Import validates the key, resolves the project name automatically, and merges it into the same configuration used by compilation and VS Code. Reimporting updates that project without duplicating it or removing other projects. Wallet login preserves imported projects belonging to other wallets.
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/cli/config.mjs

@@ -102,11 +102,47 @@ export async function installProjects(
     endpoint,
     path = configPath()
 ) {
+    if (!/^[a-f0-9]{56}$/.test(wallet))
+        throw new Error("Invalid wallet response")
+    validateProjects(projects)
+    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
+    return writeConfig(data, path)
+}
+export async function installSharedProject(
+    project,
+    endpoint,
+    path = configPath()
+) {
+    validateProjects([project])
+    const data = await readConfig(path)
+    const previous = data.profiles[project.id]
+    if (previous && previous.endpoint !== endpoint)
+        throw new Error(
+            "Project ID already exists for another debugger service"
+        )
     if (
-        !/^[a-f0-9]{56}$/.test(wallet) ||
-        !Array.isArray(projects) ||
-        !projects.length
+        previous &&
+        previous.apiKey === project.apiKey &&
+        previous.name === project.name &&
+        previous.created_at === project.created_at
     )
+        return { path, alreadyExists: true }
+    data.profiles[project.id] = { ...previous, ...project, endpoint }
+    if (!data.profiles[data.selected]) data.selected = project.id
+    await writeConfig(data, path)
+    return { path, alreadyExists: false }
+}
+function validateProjects(projects) {
+    if (!Array.isArray(projects) || !projects.length)
         throw new Error("Invalid or empty project response")
     const ids = new Set()
     for (const p of projects) {
@@ -122,16 +158,8 @@ export async function installProjects(
             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
+}
+async function writeConfig(data, path) {
     const dir = dirname(path)
     const existed = await inspect(dir, true)
     await mkdir(dir, { recursive: true, mode: 0o700 })

package/src/cli/import-key.mjs

@@ -0,0 +1,56 @@
+import { installSharedProject } from "./config.mjs"
+
+export async function importKey(
+    apiKey,
+    {
+        endpoint = "https://debugger.helios-lang.io",
+        fetchImpl = fetch,
+        save = installSharedProject,
+        log = console.log
+    } = {}
+) {
+    if (typeof apiKey !== "string" || !/^hdbg_[a-f0-9]{64}$/.test(apiKey))
+        throw new Error(
+            "Invalid debugger API key. Copy the full key from the project's Console page."
+        )
+    const origin = new URL(endpoint)
+    if (
+        origin.protocol !== "https:" ||
+        origin.username ||
+        origin.password ||
+        origin.pathname !== "/" ||
+        origin.search ||
+        origin.hash
+    )
+        throw new Error("Debugger endpoint must be an HTTPS origin")
+    let response
+    try {
+        response = await fetchImpl(origin.origin + "/v1/project", {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(10000)
+        })
+    } catch {
+        throw new Error(
+            "Could not reach the debugger service. Check your connection and try again."
+        )
+    }
+    if (response.status === 401)
+        throw new Error(
+            "This debugger API key is invalid or revoked. Ask the project owner for an active key."
+        )
+    if (!response.ok)
+        throw new Error(
+            `Debugger project lookup failed (HTTP ${response.status}). Try again later.`
+        )
+    const { id, name, created_at } = await response.json()
+    const { path, alreadyExists } = await save(
+        { id, name, created_at, apiKey },
+        origin.origin
+    )
+    if (alreadyExists) log("Key already exists")
+    else
+        log(`Imported project ${JSON.stringify(name)} into ${path}.
+Compile with helios compile --project ${JSON.stringify(name)} (or hl2ts --project ${JSON.stringify(name)}).`)
+    return { id, name, created_at }
+}

package/src/helios.mjs

@@ -10,6 +10,11 @@ try {
     } else if (command === "wallet") {
         const { walletCommand } = await import("./cli/wallet.mjs")
         await walletCommand(args)
+    } else if (command === "import-key") {
+        if (args.length !== 1)
+            throw new Error("Usage: helios import-key <api-key>")
+        const { importKey } = await import("./cli/import-key.mjs")
+        await importKey(args[0])
     } else if (command === "login") {
         if (args.some((arg) => arg !== "--no-browser"))
             throw new Error("Usage: helios login [--no-browser]")
@@ -41,7 +46,7 @@ try {
         )
     } else if (!command || ["--help", "-h", "help"].includes(command)) {
         console.log(
-            "Helios CLI\n\n  helios compile [options]  Compile contracts (same options as hl2ts)\n  helios login [--no-browser]  Install project API keys through the Console\n  helios wallet create [--network preprod] [--out wallet.json]  Generate a wallet offline\n  helios --version"
+            "Helios CLI\n\n  helios compile [options]  Compile contracts (same options as hl2ts)\n  helios login [--no-browser]  Install project API keys through the Console\n  helios import-key <api-key>  Install a shared project API key\n  helios wallet create [--network preprod] [--out wallet.json]  Generate a wallet offline\n  helios --version"
         )
     } else throw new Error(`Unknown command: ${command}. Run helios --help.`)
 } catch (error) {

package/types/cli/config.d.mts

@@ -1,5 +1,9 @@
 export function windowsAcl(path: any, directory: any, set?: boolean): Promise<void>;
 export function configPath(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
 export function readConfig(path?: string): Promise<any>;
-export function installProjects(wallet: any, projects: any, endpoint: any, path?: string): Promise<string>;
+export function installProjects(wallet: any, projects: any, endpoint: any, path?: string): Promise<any>;
+export function installSharedProject(project: any, endpoint: any, path?: string): Promise<{
+    path: string;
+    alreadyExists: boolean;
+}>;
 //# sourceMappingURL=config.d.mts.map

package/types/cli/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../src/cli/config.mjs"],"names":[],"mappings":"AAeA,oFAiCC;AACD,uGAcC;AAqBD,wDAaC;AACD,2GA2DC"}
+{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../src/cli/config.mjs"],"names":[],"mappings":"AAeA,oFAiCC;AACD,uGAcC;AAqBD,wDAaC;AACD,wGAoBC;AACD;;;GAuBC"}