@promus/cli 0.24.17

package/src/commands/init/funding-gate.ts

@@ -0,0 +1,67 @@
+import { cancel, isCancel, select } from '@clack/prompts'
+import qrcode from 'qrcode-terminal'
+import { type Address, type PublicClient, formatEther } from 'viem'
+
+export interface FundingGateOpts {
+  publicClient: PublicClient
+  operatorAddress: Address
+  requiredOg: bigint
+  /** Native gas-token symbol to display ('ETH' or '0G'). Defaults to 'ETH'. */
+  currency?: string
+  pollIntervalMs?: number
+  maxWaitMs?: number
+}
+
+export type FundingGateOutcome =
+  | { kind: 'funded'; balance: bigint }
+  | { kind: 'skip-ledger' }
+  | { kind: 'cancel' }
+
+/**
+ * Show operator address as a QR and poll balance until it meets required
+ * threshold. User can cancel or choose to proceed with minimum-only (skip
+ * full compute ledger) at any point.
+ *
+ * Console prints the QR once; the polling loop updates a single line
+ * using `process.stdout.write` so the display doesn't scroll.
+ */
+export async function fundingGate(opts: FundingGateOpts): Promise<FundingGateOutcome> {
+  const pollIntervalMs = opts.pollIntervalMs ?? 10_000
+  const maxWaitMs = opts.maxWaitMs ?? 30 * 60_000 // 30 minutes
+  const ccy = opts.currency ?? 'ETH'
+
+  console.log('')
+  console.log(`  Send at least ${formatEther(opts.requiredOg)} ${ccy} to:`)
+  console.log(`    ${opts.operatorAddress}`)
+  console.log('')
+  qrcode.generate(opts.operatorAddress, { small: true })
+  console.log('')
+
+  const start = Date.now()
+  while (Date.now() - start < maxWaitMs) {
+    const balance = await opts.publicClient.getBalance({ address: opts.operatorAddress })
+    if (balance >= opts.requiredOg) {
+      process.stdout.write('\r')
+      return { kind: 'funded', balance }
+    }
+    process.stdout.write(
+      `\r  polling... current balance ${formatEther(balance)} ${ccy} (need ${formatEther(opts.requiredOg)}) `,
+    )
+    await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+  }
+
+  process.stdout.write('\n\n')
+  const choice = await select({
+    message: 'Balance still insufficient. What now?',
+    options: [
+      { value: 'skip' as const, label: 'Skip compute ledger for now (mint + subname only)' },
+      { value: 'cancel' as const, label: 'Cancel init' },
+    ],
+    initialValue: 'cancel',
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    return { kind: 'cancel' }
+  }
+  return choice === 'skip' ? { kind: 'skip-ledger' } : { kind: 'cancel' }
+}

package/src/commands/init/model-picker.ts

@@ -0,0 +1,81 @@
+import { cancel, isCancel, select, spinner } from '@clack/prompts'
+import { type PromusNetwork, NETWORK_RPC, OGComputeBrain } from '@promus/core'
+import { formatEther } from 'viem'
+import { shortAddr } from '../../util/format'
+import { withSilencedConsole } from '../../util/silence-console'
+
+export interface ModelPick {
+  provider: string
+  model: string | null
+  inputPricePerTokenWei: bigint
+  outputPricePerTokenWei: bigint
+}
+
+/**
+ * Fetch the live 0G Compute provider catalog and prompt the user to pick
+ * one. Uses a throwaway privkey for the read-only listService call so no
+ * wallet or funds are needed at this stage.
+ *
+ * Returns `null` if the user cancels, catalog fetch fails, or the list is
+ * empty. Caller should treat `null` as "don't block init, set provider=null
+ * and let chat.tsx prompt later if needed."
+ */
+export async function pickBrainModel(opts: {
+  network: PromusNetwork
+}): Promise<ModelPick | null> {
+  const s = spinner()
+  s.start('Fetching live 0G Compute catalog')
+  type Svc = {
+    provider: string
+    model?: string
+    serviceType?: string
+    inputPrice?: string | bigint
+    outputPrice?: string | bigint
+  }
+  let services: Svc[] = []
+  try {
+    // Throwaway key — listService is a read; no funds consumed.
+    const throwawayKey = `0x${'1'.repeat(64)}`
+    services = (await withSilencedConsole(() =>
+      OGComputeBrain.listServicesFor({
+        privkeyHex: throwawayKey as `0x${string}`,
+        rpcUrl: NETWORK_RPC[opts.network],
+      }),
+    )) as unknown as Svc[]
+    s.stop(`Fetched ${services.length} providers`)
+  } catch (e) {
+    s.stop(`Catalog fetch failed: ${(e as Error).message.slice(0, 120)}`)
+    return null
+  }
+  if (services.length === 0) return null
+
+  const picked = await select({
+    message: 'Pick a brain (model)',
+    options: services.map(svc => {
+      const input = svc.inputPrice ? BigInt(svc.inputPrice) : 0n
+      const output = svc.outputPrice ? BigInt(svc.outputPrice) : 0n
+      const priceLine =
+        input > 0n || output > 0n
+          ? `in ${formatEther(input)}/tok · out ${formatEther(output)}/tok`
+          : undefined
+      return {
+        value: svc.provider,
+        label: `${svc.model ?? 'unknown'}  ${svc.serviceType ? `[${svc.serviceType}]` : ''}  ${shortAddr(svc.provider)}`,
+        hint: priceLine,
+      }
+    }),
+  })
+  if (isCancel(picked) || typeof picked !== 'string') {
+    cancel('Aborted.')
+    return null
+  }
+  const svc = services.find(s => s.provider === picked)
+  if (!svc) return null
+
+  return {
+    provider: picked,
+    model: svc.model ?? null,
+    inputPricePerTokenWei: svc.inputPrice ? BigInt(svc.inputPrice) : 0n,
+    outputPricePerTokenWei: svc.outputPrice ? BigInt(svc.outputPrice) : 0n,
+  }
+}

package/src/commands/init/operator-picker.ts

@@ -0,0 +1,263 @@
+import { existsSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { cancel, confirm, isCancel, note, password, select, text } from '@clack/prompts'
+import {
+  type PromusNetwork,
+  KeychainOperatorSigner,
+  KeystoreFileOperatorSigner,
+  type OperatorSigner,
+  type OperatorSourceHint,
+  type OperatorSourceKind,
+  RawPrivkeyOperatorSigner,
+  WalletConnectOperatorSigner,
+} from '@promus/core'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+
+interface PickerOptions {
+  network: PromusNetwork
+}
+
+export interface OperatorPickResult {
+  signer: OperatorSigner
+  hint: OperatorSourceHint
+}
+
+/**
+ * Prompt the user for their operator wallet source and return both the
+ * connected `OperatorSigner` and the metadata needed to reconstruct it
+ * later (`OperatorSourceHint`). The hint is saved to `promus.config.ts` by
+ * the wizard so subsequent commands (chat, topup, restore) can re-attach
+ * to the same source without re-prompting.
+ *
+ * Platform-aware: on macOS, all four sources are offered. On Linux/Windows
+ * the OS keychain option is hidden because libsecret/Credential-Manager
+ * support is post-MVP.
+ */
+export async function pickOperatorSigner(opts: PickerOptions): Promise<OperatorPickResult | null> {
+  const isMac = process.platform === 'darwin'
+  const choices: { value: OperatorSourceKind | 'generate'; label: string; hint?: string }[] = [
+    {
+      value: 'generate',
+      label: 'Generate new key',
+      hint: 'creates a fresh testnet wallet (save the key!)',
+    },
+    {
+      value: 'walletconnect',
+      label: 'WalletConnect',
+      hint: 'scan QR with any WC-compatible mobile wallet',
+    },
+    ...(isMac
+      ? ([
+          {
+            value: 'keychain',
+            label: 'macOS Keychain',
+            hint: 'stored in login keychain',
+          },
+        ] as const)
+      : []),
+    {
+      value: 'keystore-file',
+      label: 'Keystore file',
+      hint: 'encrypted JSON, geth format',
+    },
+    {
+      value: 'raw-privkey',
+      label: 'Raw private key',
+      hint: 'stdin prompt, for CI/scripting',
+    },
+  ]
+  const source = (await select({
+    message: 'Connect your operator wallet (owns the iNFT)',
+    options: choices,
+    initialValue: choices[0]!.value,
+  })) as OperatorSourceKind | 'generate' | symbol
+  if (isCancel(source)) {
+    cancel('Aborted.')
+    return null
+  }
+
+  switch (source) {
+    case 'generate': {
+      const privkey = generatePrivateKey()
+      const account = privateKeyToAccount(privkey)
+      note(
+        `Generated testnet wallet:\n  address: ${account.address}\n  private key: ${privkey}\n\nSAVE THIS KEY — you'll need it to reconnect later.`,
+        'new wallet',
+      )
+      const saveToFile = await confirm({
+        message: 'Save private key to ~/.promus/operator-key?',
+        initialValue: true,
+      })
+      if (!isCancel(saveToFile) && saveToFile) {
+        const keyPath = join(homedir(), '.promus', 'operator-key')
+        await writeFile(keyPath, privkey, 'utf8')
+        note(`Key saved to ${keyPath}`, 'saved')
+      }
+      return {
+        signer: new RawPrivkeyOperatorSigner({ privkey, sourceLabel: 'generated' }),
+        hint: { source: 'raw-privkey' },
+      }
+    }
+    case 'walletconnect':
+      return {
+        signer: new WalletConnectOperatorSigner({ networks: [opts.network] }),
+        hint: { source: 'walletconnect' },
+      }
+    case 'keychain': {
+      const service = await text({
+        message: 'Keychain service name',
+        placeholder: 'promus.operator',
+        validate: v => {
+          if (!v || v.length === 0) return 'Required.'
+          if (!/^[a-zA-Z0-9._-]{1,128}$/.test(v))
+            return 'Allowed characters: a-z, A-Z, 0-9, dot, underscore, hyphen (max 128).'
+          return undefined
+        },
+      })
+      if (isCancel(service)) {
+        cancel('Aborted.')
+        return null
+      }
+      const svc = service as string
+      return {
+        signer: new KeychainOperatorSigner(svc),
+        hint: { source: 'keychain', keychainService: svc },
+      }
+    }
+    case 'keystore-file': {
+      const path = await text({
+        message: 'Path to encrypted JSON keystore',
+        placeholder: '~/wallets/operator.json',
+        validate: v => {
+          if (!v) return 'Required.'
+          const expanded = v.replace(/^~/, process.env.HOME ?? '~')
+          if (!existsSync(expanded)) return `File not found: ${expanded}`
+          return undefined
+        },
+      })
+      if (isCancel(path)) {
+        cancel('Aborted.')
+        return null
+      }
+      const expanded = (path as string).replace(/^~/, process.env.HOME ?? '~')
+      const pass = await password({
+        message: 'Passphrase for the keystore',
+        validate: v => (v && v.length > 0 ? undefined : 'Required.'),
+      })
+      if (isCancel(pass)) {
+        cancel('Aborted.')
+        return null
+      }
+      return {
+        signer: new KeystoreFileOperatorSigner({ path: expanded, passphrase: pass as string }),
+        hint: { source: 'keystore-file', keystorePath: path as string },
+      }
+    }
+    case 'raw-privkey': {
+      if (process.env.PROMUS_OPERATOR_PRIVKEY) {
+        note('Using PROMUS_OPERATOR_PRIVKEY from env.', 'raw-privkey')
+        return {
+          signer: new RawPrivkeyOperatorSigner({
+            privkey: process.env.PROMUS_OPERATOR_PRIVKEY,
+            sourceLabel: 'env:PROMUS_OPERATOR_PRIVKEY',
+          }),
+          hint: { source: 'raw-privkey' },
+        }
+      }
+      const pk = await password({
+        message: 'Operator private key (hex, 0x prefix optional)',
+        validate: v => {
+          if (!v) return 'Required.'
+          const clean = v.trim().replace(/^0x/, '')
+          if (!/^[0-9a-fA-F]{64}$/.test(clean)) return 'Must be 32 bytes hex.'
+          return undefined
+        },
+      })
+      if (isCancel(pk)) {
+        cancel('Aborted.')
+        return null
+      }
+      return {
+        signer: new RawPrivkeyOperatorSigner({ privkey: pk as string, sourceLabel: 'stdin' }),
+        hint: { source: 'raw-privkey' },
+      }
+    }
+  }
+}
+
+/**
+ * Reload an `OperatorSigner` from a previously persisted hint in
+ * `promus.config.ts`. Used by chat / topup / restore / resume so the user
+ * doesn't re-pick a source every session — they only re-supply per-session
+ * secrets (passphrases / QR scans / env vars).
+ *
+ * Returns null when the hint is missing or unusable; the caller falls back
+ * to `pickOperatorSigner` for an interactive choice.
+ */
+export async function loadOperatorFromHint(
+  hint: OperatorSourceHint,
+  network: PromusNetwork,
+): Promise<OperatorSigner | null> {
+  switch (hint.source) {
+    case 'walletconnect':
+      return new WalletConnectOperatorSigner({ networks: [network] })
+    case 'keychain': {
+      if (!hint.keychainService) return null
+      return new KeychainOperatorSigner(hint.keychainService)
+    }
+    case 'keystore-file': {
+      if (!hint.keystorePath) return null
+      const expanded = hint.keystorePath.replace(/^~/, process.env.HOME ?? '~')
+      if (!existsSync(expanded)) {
+        note(`Operator keystore not found at ${expanded}; pick a new source.`, 'keystore missing')
+        return null
+      }
+      const pass = await password({
+        message: `Passphrase for operator keystore ${expanded}`,
+        validate: v => (v && v.length > 0 ? undefined : 'Required.'),
+      })
+      if (isCancel(pass)) return null
+      return new KeystoreFileOperatorSigner({
+        path: expanded,
+        passphrase: pass as string,
+      })
+    }
+    case 'raw-privkey': {
+      if (process.env.PROMUS_OPERATOR_PRIVKEY) {
+        return new RawPrivkeyOperatorSigner({
+          privkey: process.env.PROMUS_OPERATOR_PRIVKEY,
+          sourceLabel: 'env:PROMUS_OPERATOR_PRIVKEY',
+        })
+      }
+      const pk = await password({
+        message: 'Operator private key (hex, 0x prefix optional)',
+        validate: v => {
+          if (!v) return 'Required.'
+          const clean = v.trim().replace(/^0x/, '')
+          if (!/^[0-9a-fA-F]{64}$/.test(clean)) return 'Must be 32 bytes hex.'
+          return undefined
+        },
+      })
+      if (isCancel(pk)) return null
+      return new RawPrivkeyOperatorSigner({ privkey: pk as string, sourceLabel: 'stdin' })
+    }
+  }
+}
+
+/**
+ * High-level helper: load operator from config hint when available, fall
+ * back to interactive picker otherwise. Used by all post-init commands.
+ */
+export async function loadOrPickOperatorSigner(opts: {
+  network: PromusNetwork
+  hint?: OperatorSourceHint | null
+}): Promise<OperatorSigner | null> {
+  if (opts.hint) {
+    const signer = await loadOperatorFromHint(opts.hint, opts.network)
+    if (signer) return signer
+  }
+  const picked = await pickOperatorSigner({ network: opts.network })
+  return picked?.signer ?? null
+}

package/src/commands/init/resume.ts

@@ -0,0 +1,136 @@
+import { cancel, intro, note, outro, spinner } from '@clack/prompts'
+import {
+  type PromusConfig,
+  NETWORK_CHAIN_ID,
+  agentPaths,
+  explorerTxUrl,
+  fetchAndDecryptKeystore,
+  iNFTAgentId,
+  openComputeLedger,
+} from '@promus/core'
+import type { Address, Hex } from 'viem'
+import { loadOrPickOperatorSigner } from './operator-picker'
+import { readWizardState, updateWizardState } from './wizard-state'
+
+/**
+ * Resume a partial `promus init` that crashed after mint + funding. Phase 6.6
+ * requires that the keystore was uploaded to 0G Storage before resume can
+ * proceed — otherwise the agent privkey is lost (it only existed in the
+ * original wizard's RAM).
+ */
+export async function runResumeInit(opts: {
+  config: PromusConfig
+  configPath: string
+}): Promise<void> {
+  intro('promus init --resume')
+
+  const { config } = opts
+  if (!config.identity.iNFT || !config.identity.agent) {
+    cancel('No iNFT or agent address in config. Nothing to resume — run `promus init` fresh.')
+    return
+  }
+  const network = config.network
+  const contractAddress = config.identity.iNFT.contract as Address
+  const tokenId = BigInt(config.identity.iNFT.tokenId)
+  const agentAddress = config.identity.agent as Address
+  const finalAgentId = iNFTAgentId({ contractAddress, tokenId })
+  const paths = agentPaths.agent(finalAgentId)
+
+  const state = await readWizardState(paths.dir)
+  if (!state) {
+    cancel(
+      `No state file at ${paths.dir}. If init was never started, run \`promus init\` without --resume.`,
+    )
+    return
+  }
+
+  if (!state.steps.mintTx || !state.steps.agentFundedTx) {
+    cancel(
+      'Mint or agent-funding did not complete. Resume only supports steps after funding. Start fresh with `promus init` (pick Overwrite) and re-mint.',
+    )
+    return
+  }
+
+  if (!state.steps.keystorePersistedTx) {
+    cancel(
+      [
+        'Keystore was never uploaded to 0G Storage. The agent privkey only',
+        "existed in the original wizard's RAM, so it is unrecoverable now.",
+        'Start fresh with `promus init` and re-mint into a new iNFT.',
+      ].join(' '),
+    )
+    return
+  }
+
+  const operator = await loadOrPickOperatorSigner({ network, hint: config.operator })
+  if (!operator) {
+    cancel('No operator wallet available; cannot decrypt keystore to resume.')
+    return
+  }
+
+  const sUnlock = spinner()
+  sUnlock.start('Fetching keystore from 0G Storage + decrypting via operator')
+  let agentPrivkey: Hex
+  try {
+    const decrypted = await fetchAndDecryptKeystore({
+      network,
+      contractAddress,
+      tokenId,
+      signer: operator,
+      agentAddress,
+      cachePath: paths.keystore,
+    })
+    agentPrivkey = decrypted.privkeyHex
+    sUnlock.stop(`unlocked (keystore source: ${decrypted.source})`)
+  } catch (e) {
+    sUnlock.stop(`unlock failed: ${(e as Error).message.slice(0, 160)}`)
+    await operator.close?.()
+    return
+  }
+
+  if (!state.steps.ledgerOpenedTx) {
+    const s = spinner()
+    s.start('Opening 0G Compute ledger (3 0G minimum, top up later)')
+    try {
+      const status = await openComputeLedger({
+        network,
+        privkeyHex: agentPrivkey,
+        initialBalance: 3,
+        providerAddress: config.brain.provider ?? undefined,
+      })
+      await updateWizardState(paths.dir, draft => {
+        draft.steps.ledgerOpenedTx = true
+      })
+      s.stop(
+        status.alreadyExisted ? 'ledger already existed, topped up' : 'ledger opened with 3 0G',
+      )
+    } catch (e) {
+      s.stop(`ledger open failed: ${(e as Error).message.slice(0, 120)}`)
+    }
+  }
+
+  // Subname records are not resumable: the state file intentionally doesn't
+  // persist the requested label, so if text records are incomplete we tell
+  // the user to re-run `promus init` and pick the same label manually.
+  if (!state.steps.subnameClaimedTx) {
+    note(
+      'If you wanted a subname, re-run `promus init` (it can re-pick the same label).',
+      'subname not resumable',
+    )
+  }
+
+  await operator.close?.()
+
+  outro(
+    [
+      '',
+      `  agent     ${agentAddress}`,
+      `  iNFT      #${tokenId.toString()} at ${contractAddress}`,
+      `  tx        ${explorerTxUrl(network, state.steps.mintTx as Hex)}`,
+      `  keystore  ${paths.keystore} (cache of 0G Storage blob)`,
+      `  chain id  ${NETWORK_CHAIN_ID[network]}`,
+      '',
+      'Resume finished. `promus` to chat, `promus status` for health.',
+    ].join('\n'),
+  )
+}