@gravito/nova

Bun Shell Orchestration Engine for Gravito - Type-safe, shell-injection-resistant shell command execution.

Features

• 🪐 Galaxy-Ready Orchestration: Seamless PlanetCore integration via OrbitNova for system-wide command execution.
• 🛡️ Shell Injection Protection: All interpolated values are automatically escaped for maximum security.
• 🚀 Bun Native Performance: Direct usage of Bun.spawn() for minimal overhead and memory efficiency.
• 🛠️ Template Literal API: Type-safe shell commands with intuitive syntax.
• 🌊 Pipeline Support: Compose multiple commands with fluent pipe operations.
• 🐚 Safe System Bridge: The preferred choice for Orbits like Horizon and Launchpad to interact with the OS.

🌌 Role in Galaxy Architecture

In the Gravito Galaxy Architecture, Nova acts as the External Thrusters (System Interaction).

• OS Manifestation: Allows the Galaxy to manifest its logic into the physical world (the Operating System) by executing shell commands, managing processes, and interacting with legacy binaries.
• Trusted Bridge: Provides a secure "Bridge" that prevents user-supplied data from escaping the Galaxy's protection through shell injection attacks.
• Satellite Automation: Powers the automation scripts and background maintenance tasks triggered by Horizon or Forge.

graph TD
    S[Satellite] -->|Run Command| Nova{Nova Thrusters}
    Nova -->|Escape| Val[Arguments Validation]
    Val -->|Execute| OS([Operating System])
    OS -->|Output| Nova
    Nova -->|Result| S

Installation

bun add @gravito/nova

Quick Start

Standalone Usage

import { Shell } from '@gravito/nova'

// Simple command execution
const result = await Shell.run`echo hello`
console.log(result.stdout) // "hello"

// Get text output directly
const text = await Shell.text`npm whoami`

// Parse JSON output
const data = await Shell.json`curl https://api.example.com/data`

// Array of lines
const lines = await Shell.run`ls -la ${directory}`.lines()

With PlanetCore

import { OrbitNova, Shell } from '@gravito/nova'
import { PlanetCore } from '@gravito/core'

const core = new PlanetCore()
core.addOrbit(new OrbitNova({ exposeAs: 'shell' }))

// In controllers
async handle(ctx: GravitoContext) {
  const result = await ctx.get('shell').run`ls -la`
}

📚 Documentation

Detailed guides and references for the Galaxy Architecture:

• 🏗️ Architecture Overview — Type-safe shell orchestration core.
• 🐚 System Orchestration — NEW: Safe command execution and pipelines.
• 🛡️ Security Rules — Preventing shell injection.

API

Shell

Static facade for shell command execution.

Shell.run(strings, ...values): ShellCommand

Execute a shell command with template literal syntax.

const result = await Shell.run`echo ${message}`

Shell.text(strings, ...values): Promise<string>

Execute a command and get stdout as string.

const output = await Shell.text`cat ${file}`

Shell.json<T>(strings, ...values): Promise<T>

Execute a command and parse stdout as JSON.

const data = await Shell.json`curl ${url}`

Shell.cmd(strings, ...values): ShellCommand

Create a command for use in pipelines.

const result = await Shell.pipe(
  Shell.cmd`cat ${file}`,
  Shell.cmd`grep ${pattern}`,
  Shell.cmd`head -n ${count}`
).text()

Shell.pipe(...commands): Pipeline

Create a pipeline from multiple commands.

const output = await Shell.pipe(
  Shell.cmd`cat input.txt`,
  Shell.cmd`sort`,
  Shell.cmd`uniq`
).run()

ShellCommand

Chainable command builder.

Configuration Methods

Shell.run`echo test`
  .cwd('/path/to/dir')        // Set working directory
  .env({ VAR: 'value' })      // Set environment variables
  .quiet()                     // Suppress output
  .nothrow()                   // Don't throw on error
  .timeout(5000)               // Set timeout in ms
  .run()                       // Execute

Execution Methods

const cmd = Shell.run`echo hello`

await cmd.run()               // Get ShellResult
await cmd.text()              // Get stdout as string
await cmd.lines()             // Get stdout as string[]
await cmd.json<T>()           // Parse stdout as JSON

ShellResult

interface ShellResult {
  exitCode: number       // Process exit code
  stdout: string         // Standard output
  stderr: string         // Standard error
  success: boolean       // Whether exitCode === 0
}

Errors

import { NovaError, NovaShellError } from '@gravito/nova'

try {
  await Shell.run`false`
} catch (error) {
  if (error instanceof NovaShellError) {
    console.log(error.exitCode)
    console.log(error.stdout)
    console.log(error.stderr)
  }
}

Shell Injection Protection

All interpolated values are automatically escaped:

// Safe - even with malicious input
const userInput = '$(rm -rf /)'
await Shell.run`echo ${userInput}` // Outputs literal string, not executed

Examples

File Operations

// Check if file exists
const result = await Shell.run`test -f ${filepath}`.nothrow()
const exists = result.success

// Count lines in file
const lineCount = await Shell.text`wc -l < ${filepath}`

// Find files
const files = await Shell.run`find ${dir} -name ${pattern}`.lines()

Process Management

// Get process info
const ps = await Shell.text`ps aux | grep ${processName}`

// Kill process
await Shell.run`kill ${pid}`.nothrow()

Git Operations

// Get current branch
const branch = await Shell.text`git branch --show-current`

// Get commit log
const commits = await Shell.run`git log --oneline -n ${count}`.lines()

NPM/Package Management

// Install dependencies
await Shell.run`npm install`

// Run script
const output = await Shell.text`npm run ${scriptName}`

Error Handling

By default, non-zero exit codes throw errors:

try {
  await Shell.run`command that fails`
} catch (error) {
  // Handle error
}

Suppress errors with .nothrow():

const result = await Shell.run`command that fails`.nothrow()
if (!result.success) {
  console.log(`Exit code: ${result.exitCode}`)
}

Performance

• No dependencies: Pure Bun implementation
• Minimal overhead: Direct Bun.spawn() usage
• Memory efficient: Streams-based output handling
• Type safe: Full TypeScript support with strict mode

Testing

# Run tests
bun test

# With coverage
bun test --coverage

# Type checking
bun run typecheck

License

MIT

Framework Integration

Nova is integrated into several Gravito packages:

• @gravito/horizon - Task scheduler and cron jobs now use Nova for shell execution

  • Cleaner Process.ts implementation with automatic escaping
  • Full backward compatibility with existing ProcessResult interface

• @gravito/launchpad - Docker container orchestration now uses Nova

  • Enhanced cache directory operations with shell injection protection
  • Docker CLI commands preserved with native spawning

Related Packages

• @gravito/core - PlanetCore framework
• @gravito/photon - HTTP engine
• @gravito/atlas - ORM
• @gravito/horizon - Task scheduler (integrated)
• @gravito/launchpad - Docker orchestration (integrated)
• @gravito/xenon - FFI wrapper (complementary)

Support

For issues and discussions, visit GitHub Issues