diff --git a/README.md b/README.md index b40d7eb..7aa4c65 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ ### Installation ```bash -npm install devbox-sdk +npm install @labring/devbox-sdk ``` ### Secure Code Execution ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' // Initialize SDK const sdk = new DevboxSDK({ @@ -99,7 +99,7 @@ Each sandbox runs in an isolated Kubernetes Pod, ensuring: This is a monorepo containing multiple packages: -### devbox-sdk (Main Package) +### @labring/devbox-sdk (Main Package) The primary TypeScript SDK for secure sandbox execution. See [packages/sdk/README.md](./packages/sdk/README.md) for detailed documentation. ### devbox-shared diff --git a/apps/docs/components/landing/footer.tsx b/apps/docs/components/landing/footer.tsx index 7a4f874..8100544 100644 --- a/apps/docs/components/landing/footer.tsx +++ b/apps/docs/components/landing/footer.tsx @@ -31,7 +31,7 @@ export function Footer() {
  • NPM diff --git a/apps/docs/components/landing/hero-section.tsx b/apps/docs/components/landing/hero-section.tsx index b4531ed..d222bd1 100644 --- a/apps/docs/components/landing/hero-section.tsx +++ b/apps/docs/components/landing/hero-section.tsx @@ -95,7 +95,7 @@ export function HeroSection() { import{' '} {'{ DevboxSDK }'}{' '} from{' '} - 'devbox-sdk' + '@labring/devbox-sdk' {'\n\n'} {'// Initialize SDK'} {'\n'} diff --git a/apps/docs/content/docs/api/devbox-instance.mdx b/apps/docs/content/docs/api/devbox-instance.mdx index 4d47bfa..ec10db0 100644 --- a/apps/docs/content/docs/api/devbox-instance.mdx +++ b/apps/docs/content/docs/api/devbox-instance.mdx @@ -408,7 +408,7 @@ waitForReady( ## Complete Example ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ kubeconfig: process.env.KUBECONFIG diff --git a/apps/docs/content/docs/api/devbox-sdk.mdx b/apps/docs/content/docs/api/devbox-sdk.mdx index 5865eca..0aae0c3 100644 --- a/apps/docs/content/docs/api/devbox-sdk.mdx +++ b/apps/docs/content/docs/api/devbox-sdk.mdx @@ -25,7 +25,7 @@ new DevboxSDK(config: DevboxSDKConfig) ### Example ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ kubeconfig: process.env.KUBECONFIG, @@ -212,7 +212,7 @@ try { ## Complete Example ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' async function main() { const sdk = new DevboxSDK({ diff --git a/apps/docs/content/docs/api/types.mdx b/apps/docs/content/docs/api/types.mdx index 82cd5be..ad97465 100644 --- a/apps/docs/content/docs/api/types.mdx +++ b/apps/docs/content/docs/api/types.mdx @@ -200,7 +200,7 @@ import type { ProcessExecResponse, FileChangeEvent, GitCloneOptions -} from 'devbox-sdk' +} from '@labring/devbox-sdk' ``` ## Next Steps diff --git a/apps/docs/content/docs/examples/ai-agent-workflow.mdx b/apps/docs/content/docs/examples/ai-agent-workflow.mdx index 42b27cc..444b827 100644 --- a/apps/docs/content/docs/examples/ai-agent-workflow.mdx +++ b/apps/docs/content/docs/examples/ai-agent-workflow.mdx @@ -10,7 +10,7 @@ This example demonstrates a complete workflow for executing AI-generated code sa ## Complete Example ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' async function executeAIAgent(aiGeneratedCode: string) { const sdk = new DevboxSDK({ @@ -114,7 +114,7 @@ import { DevboxSDKError, FileOperationError, ValidationError -} from 'devbox-sdk' +} from '@labring/devbox-sdk' async function safeExecuteAI(code: string) { const sdk = new DevboxSDK({ @@ -226,4 +226,5 @@ async function processAIBatch(tasks: Array<{ id: string; code: string }>) { - Learn about [Automation Tasks](/docs/examples/automation-tasks) - Explore [CI/CD Integration](/docs/examples/ci-cd-integration) +- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow diff --git a/apps/docs/content/docs/examples/automation-tasks.mdx b/apps/docs/content/docs/examples/automation-tasks.mdx index 79871e5..4a6c9da 100644 --- a/apps/docs/content/docs/examples/automation-tasks.mdx +++ b/apps/docs/content/docs/examples/automation-tasks.mdx @@ -10,7 +10,7 @@ Execute untrusted automation scripts safely in isolated sandboxes. ## Basic Automation ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' async function runAutomation(script: string) { const sdk = new DevboxSDK({ @@ -249,5 +249,6 @@ async function processFiles( ## Next Steps - Learn about [CI/CD Integration](/docs/examples/ci-cd-integration) +- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow - Explore [API Reference](/docs/api/devbox-instance) diff --git a/apps/docs/content/docs/examples/ci-cd-integration.mdx b/apps/docs/content/docs/examples/ci-cd-integration.mdx index a99cb2c..73d64fb 100644 --- a/apps/docs/content/docs/examples/ci-cd-integration.mdx +++ b/apps/docs/content/docs/examples/ci-cd-integration.mdx @@ -37,7 +37,7 @@ jobs: ```typescript // scripts/ci-test.js -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' import fs from 'fs' async function runCITests() { @@ -255,6 +255,7 @@ async function runParallelTests(testSuites: string[]) { ## Next Steps +- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow - Read [API Reference](/docs/api/devbox-sdk) - Explore [Guides](/docs/guides/secure-code-execution) diff --git a/apps/docs/content/docs/examples/full-lifecycle.mdx b/apps/docs/content/docs/examples/full-lifecycle.mdx new file mode 100644 index 0000000..a7d3ee4 --- /dev/null +++ b/apps/docs/content/docs/examples/full-lifecycle.mdx @@ -0,0 +1,254 @@ +--- +title: Full Lifecycle Example +description: Complete example demonstrating the full devbox lifecycle from creation to cleanup +--- + +# Full Lifecycle Example + +This example demonstrates a complete workflow for creating, managing, and cleaning up a devbox instance. It covers environment setup, devbox creation, execution of commands, and proper resource cleanup. + +## Complete Example + +This example shows how to: + +- Load environment variables and kubeconfig +- Create a devbox instance +- Start the devbox and wait for it to be ready +- Execute commands in the devbox +- Handle errors properly +- Clean up resources + +```typescript +import { config as loadEnv } from 'dotenv' +import { existsSync, readFileSync } from 'node:fs' +import { resolve, dirname } from 'node:path' +import { fileURLToPath } from 'node:url' +import { DevboxSDK } from '@labring/devbox-sdk' +import { DevboxRuntime } from '@labring/devbox-sdk' + +// Load environment variables from .env file +const __filename = fileURLToPath(import.meta.url) +const __dirname = dirname(__filename) + +const envPaths = [ + resolve(__dirname, '.env'), + resolve(__dirname, '../.env'), + resolve(__dirname, '../../.env'), + resolve(process.cwd(), '.env'), +] + +let envLoaded = false +for (const envPath of envPaths) { + if (existsSync(envPath)) { + loadEnv({ path: envPath, override: false }) + console.log(`โœ… Loaded environment variables from ${envPath}`) + envLoaded = true + break + } +} + +if (!envLoaded) { + console.warn('โš ๏ธ .env file not found, using system environment variables') +} + +if (!process.env.KUBECONFIG) { + console.error('โŒ Missing required environment variable: KUBECONFIG') + process.exit(1) +} + +let kubeconfigContent = process.env.KUBECONFIG + +// Handle kubeconfig as file path or content +if (!kubeconfigContent.includes('apiVersion') && existsSync(kubeconfigContent)) { + kubeconfigContent = readFileSync(kubeconfigContent, 'utf-8') +} else if (kubeconfigContent.includes('\\n')) { + kubeconfigContent = kubeconfigContent.replace(/\\n/g, '\n') +} + +const SDK_CONFIG = { + kubeconfig: kubeconfigContent, + http: { + timeout: 300000, // 5 minutes + retries: 3, + rejectUnauthorized: false, + }, +} + +// Generate unique devbox name +const generateDevboxName = (prefix: string) => { + const timestamp = Date.now() + const random = Math.floor(Math.random() * 1000) + const sanitizedPrefix = prefix.replace(/\./g, '-') + return `example-${sanitizedPrefix}-${timestamp}-${random}` +} + +async function main() { + const sdk = new DevboxSDK(SDK_CONFIG) + const name = generateDevboxName('full-lifecycle') + + try { + console.log('๐Ÿš€ Starting full lifecycle example...') + console.log(`๐Ÿ“ฆ Creating devbox: ${name}`) + + // 1. Create devbox + const devbox = await sdk.createDevbox({ + name, + runtime: DevboxRuntime.TEST_AGENT, + resource: { cpu: 1, memory: 2 }, + }) + + console.log(`โœ… Devbox created: ${devbox.name}`) + console.log('โณ Starting devbox...') + + // 2. Start devbox + await devbox.start() + + // 3. Wait for devbox to be ready + let currentDevbox = await sdk.getDevbox(name) + const startTime = Date.now() + const timeout = 30000 // 30 seconds + + while (currentDevbox.status !== 'Running' && Date.now() - startTime < timeout) { + await new Promise(resolve => setTimeout(resolve, 2000)) + currentDevbox = await sdk.getDevbox(name) + process.stdout.write('.') + } + + console.log('') + console.log(`โœ… Devbox is ${currentDevbox.status}`) + + if (currentDevbox.status !== 'Running') { + throw new Error(`Devbox failed to start. Status: ${currentDevbox.status}`) + } + + // 4. Execute commands in the devbox + console.log('') + console.log('๐Ÿ” Testing command execution...') + + // Method 1: Execute command with arguments + const homeResult1 = await currentDevbox.execSync({ + command: 'echo', + args: ['$HOME'], + }) + console.log(`๐Ÿ“ HOME: ${homeResult1.stdout.trim()}`) + + // Method 2: Execute command with environment variable expansion + const homeResult2 = await currentDevbox.execSync({ + command: 'echo', + args: ['My home is $HOME'], + }) + console.log(`๐Ÿ“ Result: ${homeResult2.stdout.trim()}`) + + // Method 3: Execute shell command with pipes + const homeResult3 = await currentDevbox.execSync({ + command: 'echo $HOME | wc -c', + }) + console.log(`๐Ÿ“ HOME length: ${homeResult3.stdout.trim()} characters`) + + // 5. Additional operations can be added here: + // - File operations (writeFile, readFile, listFiles) + // - Git operations (clone, pull, push) + // - Process management (exec, getProcessStatus) + // - File watching (watchFiles) + + console.log('') + console.log('๐ŸŽ‰ Full lifecycle example completed successfully!') + + } catch (error) { + console.error('โŒ Error occurred:', error) + throw error + } finally { + // 6. Always clean up resources + try { + const devboxToDelete = await sdk.getDevbox(name).catch(() => null) + if (devboxToDelete) { + console.log(`๐Ÿงน Cleaning up devbox: ${name}`) + await devboxToDelete.delete() + console.log('โœ… Devbox deleted successfully') + } + } catch (error) { + console.warn('โš ๏ธ Failed to delete devbox:', error) + } + + await sdk.close() + console.log('โœ… SDK connections closed') + } +} + +main().catch((error) => { + console.error('Failed to run example:', error) + process.exit(1) +}) +``` + +## Key Features Demonstrated + +### 1. Environment Configuration + +The example shows how to: +- Load environment variables from multiple possible locations +- Handle kubeconfig as both file path and content string +- Configure SDK with appropriate timeouts and retry settings + +### 2. Devbox Lifecycle Management + +- **Creation**: Create a devbox with specified runtime and resources +- **Starting**: Start the devbox instance +- **Status Checking**: Poll for devbox status until it's ready +- **Cleanup**: Properly delete the devbox and close SDK connections + +### 3. Command Execution + +The example demonstrates three methods of executing commands: +- Direct command execution with arguments +- Environment variable expansion in commands +- Shell features like pipes + +### 4. Error Handling + +- Try-catch blocks for error handling +- Proper cleanup in finally block +- Graceful handling of cleanup errors + +## Running the Example + +1. **Install dependencies**: + +```bash +npm install @labring/devbox-sdk dotenv +``` + +2. **Set up environment variables**: + +Create a `.env` file or set the `KUBECONFIG` environment variable: + +```bash +export KUBECONFIG=/path/to/your/kubeconfig +``` + +Or in a `.env` file: + +``` +KUBECONFIG=/path/to/your/kubeconfig +``` + +3. **Run the example**: + +```bash +node full-lifecycle.js +``` + +## Best Practices + +1. **Always clean up**: Use try-finally blocks to ensure resources are cleaned up even if errors occur +2. **Generate unique names**: Use timestamps and random numbers to avoid naming conflicts +3. **Wait for readiness**: Always wait for devbox to be in "Running" status before executing commands +4. **Handle timeouts**: Set appropriate timeouts for operations that might take time +5. **Error handling**: Catch and handle errors appropriately, logging useful information + +## Next Steps + +- Learn about [File Operations](/docs/guides/file-operations) +- Explore [Git Integration](/docs/guides/git-integration) +- Read the [API Reference](/docs/api/devbox-sdk) + diff --git a/apps/docs/content/docs/getting-started/configuration.mdx b/apps/docs/content/docs/getting-started/configuration.mdx index 7a9a1d0..65b95d3 100644 --- a/apps/docs/content/docs/getting-started/configuration.mdx +++ b/apps/docs/content/docs/getting-started/configuration.mdx @@ -10,7 +10,7 @@ description: Configure Devbox SDK for your needs When creating a `DevboxSDK` instance, you can configure various options: ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ // Required: Kubernetes configuration @@ -157,7 +157,7 @@ export KUBECONFIG=/path/to/kubeconfig ## Example: Production Configuration ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ kubeconfig: process.env.KUBECONFIG, diff --git a/apps/docs/content/docs/getting-started/installation.mdx b/apps/docs/content/docs/getting-started/installation.mdx index 15437cf..77c4541 100644 --- a/apps/docs/content/docs/getting-started/installation.mdx +++ b/apps/docs/content/docs/getting-started/installation.mdx @@ -15,19 +15,19 @@ description: Install and configure Devbox SDK ## Install the Package ```bash -npm install devbox-sdk +npm install @labring/devbox-sdk ``` Or with yarn: ```bash -yarn add devbox-sdk +yarn add @labring/devbox-sdk ``` Or with pnpm: ```bash -pnpm add devbox-sdk +pnpm add @labring/devbox-sdk ``` ## Kubernetes Configuration @@ -43,7 +43,7 @@ export KUBECONFIG=/path/to/your/kubeconfig ### Option 2: File Path ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ kubeconfig: '/path/to/your/kubeconfig' @@ -53,7 +53,7 @@ const sdk = new DevboxSDK({ ### Option 3: Kubeconfig Content ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' import fs from 'fs' const kubeconfigContent = fs.readFileSync('/path/to/kubeconfig', 'utf-8') @@ -68,7 +68,7 @@ const sdk = new DevboxSDK({ Create a simple test file to verify your installation: ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' const sdk = new DevboxSDK({ kubeconfig: process.env.KUBECONFIG diff --git a/apps/docs/content/docs/getting-started/quick-start.mdx b/apps/docs/content/docs/getting-started/quick-start.mdx index 4146a26..10f9799 100644 --- a/apps/docs/content/docs/getting-started/quick-start.mdx +++ b/apps/docs/content/docs/getting-started/quick-start.mdx @@ -10,7 +10,7 @@ This guide will help you create your first secure sandbox and execute code safel ## Create Your First Sandbox ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' // Initialize SDK const sdk = new DevboxSDK({ @@ -129,7 +129,7 @@ await sdk.close() Here's a complete example that demonstrates the full workflow: ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' async function main() { const sdk = new DevboxSDK({ @@ -172,6 +172,7 @@ main().catch(console.error) ## Next Steps +- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow - Learn about [Secure Code Execution](/docs/guides/secure-code-execution) - Explore [File Operations](/docs/guides/file-operations) - Read the [API Reference](/docs/api/devbox-sdk) diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx index a243551..bc73404 100644 --- a/apps/docs/content/docs/index.mdx +++ b/apps/docs/content/docs/index.mdx @@ -21,13 +21,13 @@ Devbox SDK provides **container-based isolation** for safe code execution. Each ### Installation ```bash -npm install devbox-sdk +npm install @labring/devbox-sdk ``` ### Your First Sandbox ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' // Initialize SDK const sdk = new DevboxSDK({ @@ -128,6 +128,7 @@ await sandbox.git.pull('/workspace/repo') - **[Guides](/docs/guides/secure-code-execution)** - Usage guides and best practices - **[API Reference](/docs/api/devbox-sdk)** - Complete API documentation - **[Examples](/docs/examples/ai-agent-workflow)** - Real-world examples + - [Full Lifecycle Example](/docs/examples/full-lifecycle) - Complete devbox lifecycle from creation to cleanup ## Next Steps diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 1f4be59..2ad50bb 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -1,11 +1,11 @@ -# devbox-sdk +# @labring/devbox-sdk **Secure Sandbox SDK for Isolated Code Execution.** Execute AI-generated code, run automation tasks, and test untrusted code with zero risk to your infrastructure. ## Installation ```bash -npm install devbox-sdk +npm install @labring/devbox-sdk ``` ## Requirements @@ -18,7 +18,7 @@ npm install devbox-sdk ### Secure Code Execution ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' // Initialize SDK const sdk = new DevboxSDK({ @@ -383,7 +383,7 @@ import { FileOperationError, DevboxNotFoundError, ValidationError -} from 'devbox-sdk' +} from '@labring/devbox-sdk' try { await sandbox.writeFile('/invalid/path', 'content') @@ -410,7 +410,7 @@ try { ### Complete AI Agent Workflow ```typescript -import { DevboxSDK } from 'devbox-sdk' +import { DevboxSDK } from '@labring/devbox-sdk' async function runAIAgent() { const sdk = new DevboxSDK({ @@ -457,7 +457,7 @@ import type { FileMap, ProcessExecOptions, GitCloneOptions -} from 'devbox-sdk' +} from '@labring/devbox-sdk' ``` ## Performance diff --git a/packages/sdk/package.json b/packages/sdk/package.json index 9b16c0c..8a44e2d 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -1,5 +1,5 @@ { - "name": "devbox-sdk", + "name": "@labring/devbox-sdk", "version": "1.1.2", "description": "Enterprise TypeScript SDK for Sealos Devbox management", "main": "./dist/index.cjs",