feat(cli): initialize SuperAdmin natively and connect contract IDs po…

[melvilmz]

📌 Description

This PR implements the deployment orchestrator features for initializing SuperAdmin natively on-chain (#694) and connecting deployed contract IDs post-deployment (#693).

Closes #694
Closes #693

---

🚀 Key Features & Changes

1. Native SuperAdmin Initialization (#694)

• Automatic Initialization: Implemented initializeSuperAdmin() in cli/src/orchestrator/init-superadmin.ts to automatically construct and submit the contract initialize() transaction using the deployer's keypair.
• On-Chain Role Verification: Performs on-chain verification (verifySuperAdmin(), hasRole(), getAdmin()) via simulation query to guarantee the deployer holds the SuperAdmin / Admin role post-initialization.
• Configuration Persistence: Automatically updates .bc-forge.json with the deployer public key and initialized contract address.
• CLI Command: Added bc-forge init-superadmin with flags for --contract-id, --deployer, --secret-key, --name, --symbol, --decimals, and --no-verify.

2. Post-Deployment Contract ID Connection (#693)

• Contract Linking Step: Implemented connectContractIds() / linkContracts() in cli/src/orchestrator/connect-contracts.ts to connect deployed contract IDs to dependent contracts.
• Admin-to-Token Connection: Passes the deployed Admin Contract ID to the Token Contract via set_admin_contract setup invocations.
• Token-to-Dependent Contracts: Connects the Token Contract ID to dependent contracts (e.g. Vesting, Wrapper, Split).
• Configuration Persistence: Records linked contract mappings (linkedContracts, adminContractId, tokenContractId) to .bc-forge.json.
• CLI Command: Added bc-forge connect (alias bc-forge link) with flags for --admin, --token, --vesting, --wrapper, --secret-key, and --file.

3. Unified Deployment Orchestrator

• Orchestrator Pipeline: Implemented runDeploymentOrchestrator() in cli/src/orchestrator/orchestrator.ts to coordinate the full end-to-end lifecycle: initialize SuperAdmin -> connect contract IDs post-deployment -> verify all roles & links -> save deployment state.
• CLI Command: Added bc-forge orchestrate.

4. TypeScript SDK Enhancements (@bc-forge/sdk)

• Added RBAC & connection methods to bcForgeClient and MockBcForgeClient:
  • getAdmin(): Promise<string>
  • hasRole(role: Role, address: string): Promise<boolean>
  • verifySuperAdmin(address: string): Promise<boolean>
  • grantRole(role: Role, address: string, source: Keypair): Promise<TransactionResult>
  • revokeRole(role: Role, address: string, source: Keypair): Promise<TransactionResult>
  • setAdminContract(adminContractId: string, source: Keypair): Promise<TransactionResult>
  • setDependentToken(tokenContractId: string, source: Keypair): Promise<TransactionResult>

5. Config Schema Updates

• Updated cli/src/schema/bc-forge.schema.json and cli/src/utils/config-parser.ts to support adminContractId, tokenContractId, and linkedContracts under contract deployment metadata.

---

🧪 Test Coverage

Added comprehensive unit test suites covering both happy paths and expected error states:

• cli/src/orchestrator/__tests__/init-superadmin.test.ts:
  • Validates C-address and G-address helpers
  • Native initialization and on-chain SuperAdmin verification
  • Custom name/symbol/decimals parameters
  • Config file persistence
  • Error states: missing contract ID, invalid ID format, missing/invalid secret key, invalid deployer address
• cli/src/orchestrator/__tests__/connect-contracts.test.ts:
  • Linking Admin Contract ID to Token Contract
  • Linking Token Contract ID to Vesting & Wrapper contracts
  • Custom contract link rules
  • Config file persistence
  • Error states: missing contract IDs, invalid ID formats, missing secret key
• cli/src/orchestrator/__tests__/orchestrator.test.ts:
  • Full orchestrator execution pipeline & error handling
• cli/src/utils/__tests__/config-parser.test.ts:
  • Schema validation for deployed and linked contract properties
• sdk/src/client.test.ts:
  • Unit tests for SDK role management and contract connection methods

---

✅ Checklist

• Code compiles and adheres to Soroban/Rust/TypeScript best practices
• Unit tests cover happy paths and expected error states
• CLI commands (init-superadmin, connect, orchestrate) integrated and documented
• Schema and config parser support linked contract metadata
• All tests and validations pass successfully

Related issues

Closes #694
Closes #693
Closes #692
Closes #691

[drips-wave]

@melvilmz Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[p3ris0n]

@melvilmz please fix CI