feat: runtime plugins, env lock, and docs updates

[dev-dami]

Summary

• add runtime plugin system + environment lock/manifest support
• expose env/lock CLI commands and runtime overrides
• add validation utilities/tests and update docs/tooling

Testing

• bun run lint
• bun run test (Docker daemon not accessible in this environment)
• bun run build

Summary by CodeRabbit

• New Features

  • Added ignite lock command for environment locking and drift detection.
  • Added ignite env command to display environment information and supported runtimes.
  • Expanded runtime support to include Bun (default), Node, Deno, and QuickJS with version specifications.
  • Added CPU limit configuration for services.
  • Added runtime override support in ignite run command.

• Documentation

  • Updated API, architecture, and walkthrough documentation to reflect multi-runtime support and security guidance.

• Chores

  • Established Bun as the default runtime; removed Node runtime artifacts.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​typescript-eslint/​parser@​8.53.1
	@​typescript-eslint/​eslint-plugin@​8.53.1
	eslint@​9.39.2

View full report

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR transitions the project from Node.js-focused to Bun-first with multi-runtime support (Bun, Node, Deno, QuickJS), introduces a dynamic runtime plugin system, adds environment manifest locking and drift detection, implements new CLI commands (lock, env) with runtime override capability, removes static Node runtime packages, and updates all documentation and examples accordingly.

Changes

Cohort / File(s)	Summary
Documentation Updates AGENTS.md, CONTRIBUTING.md, README.md, docs/api.md, docs/architecture.md, docs/threat-model.md, docs/walkthrough.md	Documentation overhaul: Added Bun enforcement in AGENTS.md; removed Node runtime Dockerfile reference in CONTRIBUTING.md; expanded supported runtimes table in README.md with Bun as default and security notes; extensively updated API docs with new ignite lock and ignite env commands, runtime versioning syntax (e.g., bun@1.3, node@20), and cpuLimit config; refactored architecture docs to reflect Bun-first approach; minor formatting adjustments in threat model.
Runtime Plugin System packages/core/src/runtime/runtime-plugin.ts, packages/core/src/runtime/runtime-registry.ts, packages/core/src/runtime/runtime.types.ts, packages/shared/src/types.ts	Introduced pluggable runtime architecture: new RuntimePlugin and RuntimePluginConfig interfaces enable dynamic Dockerfile generation per runtime. Replaced static RuntimeName type with generic string-based runtime specs. Added parseRuntime() and formatRuntime() utilities for version-aware runtime parsing. Registry now supports custom runtime registration/unregistration. Built-in plugins for Bun, Node, Deno, QuickJS with configurable base images, default entries, and version support.
Environment Management packages/core/src/runtime/environment.ts	New module for service runtime manifests: added EnvironmentManifest and EnvironmentInfo types; implemented manifest lifecycle functions (loadEnvironmentManifest, saveEnvironmentManifest, createEnvironmentManifest); drift detection via checkEnvironmentDrift; manifest persistence via lockEnvironment; pretty-printing via formatEnvironmentInfo. Detects and hashes dependency files; tracks runtime versions and checksums.
Execution & Docker Updates packages/core/src/execution/execute.ts, packages/core/src/runtime/docker-runtime.ts	Refactored Dockerfile handling: replaced static path resolution with dynamic generation via runtimeConfig.plugin.generateDockerfile(version). Removed findRuntimeRoot function. Added temporary build directory for generated Dockerfiles with cleanup guarantees. Integrated CPU limit support: added cpuLimit field to DockerRunOptions and passed it to dockerRun.
CLI Commands - New & Updated packages/cli/src/commands/init.ts, packages/cli/src/commands/lock.ts, packages/cli/src/commands/env.ts, packages/cli/src/commands/run.ts, packages/cli/src/index.ts	init: Refactored to use runtime config for entry resolution; validates runtimes dynamically; creates templates with detected entry type (TS/JS). lock: New command to create/update environment manifests with --update and --check options. env: New command to display service environment info or list supported runtimes with --runtimes flag. run: Added --runtime option to override service runtime. index.ts: Wired new lock and env commands; extended run with runtime override.
Shared Types & Validation packages/shared/src/types.ts, packages/shared/src/validation.ts, packages/shared/src/index.ts	Removed rigid RuntimeName type; ServiceConfig.service.runtime now accepts any string with optional version. Added cpuLimit?: number to service config. New RuntimeSpec interface (name + optional version) and EnvironmentManifest interface for lockfile structure. Added Docker name validation utilities: DOCKER_NAME_REGEX, validateDockerName(), isValidDockerName().
Security Policy Updates packages/core/src/security/policy.ts, packages/core/src/security/security.types.ts	Removed network-level policy fields (allowedHosts, allowedPorts) and filesystem-level fields (allowedWritePaths, blockedReadPaths) from PolicyFile interfaces. Simplified mergePolicies and policyToDockerOptions to hardcode /tmp for tmpfs instead of deriving from policy.
HTTP Server & Tests packages/http/src/server.ts, packages/http/src/__tests__/security.test.ts, packages/http/src/__tests__/server.test.ts	server.ts: Replaced inline validation with validateDockerName call; added managed cleanup interval with proper lifecycle handling in stop(). security.test.ts: New comprehensive test suite covering authentication (API key/Bearer token), rate limiting per client IP, service name validation (path traversal, case sensitivity). server.test.ts: Added Docker availability checks; guarded tests to skip when Docker unavailable.
Service Loading & Validation packages/core/src/service/load-service.ts	Enhanced validation: replaced inline Docker name checks with validateDockerName() call; added explicit cpuLimit validation (must be positive number if defined).
Test Updates packages/core/src/__tests__/runtime-registry.test.ts, packages/core/src/__tests__/load-service.test.ts, packages/core/src/__tests__/docker-execution.test.ts, packages/shared/src/__tests__/validation.test.ts	runtime-registry.test.ts: Expanded to cover new registry functions (registerRuntime, unregisterRuntime, getRuntimePlugin, getSupportedVersions); added version and plugin property tests; custom runtime lifecycle testing. load-service.test.ts: Updated expected runtime from node to bun for image-resizer fixture. docker-execution.test.ts: Removed per-suite pending() gate; tests now use inline early-return guards. validation.test.ts: New suite for Docker name regex and validation functions.
Build & Release Scripts scripts/build-binaries.ts, scripts/release.ts, install.sh	Removed Node runtime from build pipeline: no longer creates runtime-node directory/artifacts or includes it in release archive; tar command packages only runtime-bun. Updated release.ts to exclude packages/runtime-node/package.json from version bumping. Removed Node runtime copy step in install.sh.
Configuration & Examples package.json, eslint.config.mjs, examples/image-resizer/index.ts, examples/image-resizer/service.yaml	package.json: Bumped version to 0.6.1; added ESLint script and dev dependencies (eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin). eslint.config.mjs: New flat config module with TypeScript ESLint parser setup. image-resizer example: Added strong typing (interfaces ResizeEvent, ResizeResponse); changed runtime from node to bun and entry from index.js to index.ts.
Removed Files packages/runtime-node/Dockerfile, packages/runtime-node/package.json	Deleted static Node runtime Dockerfile and package.json as runtime now generated dynamically via plugin system.
Core Public API packages/core/src/index.ts	Expanded public exports: added runtime registry utilities (registerRuntime, unregisterRuntime, getRuntimePlugin, getSupportedVersions); added plugin factory and built-in runtime constants (BUILTIN_RUNTIMES, BUN_RUNTIME, NODE_RUNTIME, DENO_RUNTIME, QUICKJS_RUNTIME); added environment manifest functions (loadEnvironmentManifest, saveEnvironmentManifest, createEnvironmentManifest, checkEnvironmentDrift, lockEnvironment, formatEnvironmentInfo); exported types RuntimePlugin, RuntimePluginConfig, EnvironmentInfo.

Sequence Diagram(s)

sequenceDiagram
    participant CLI
    participant Init as init Command
    participant Registry as Runtime Registry
    participant Config as Runtime Config
    participant FS as File System
    
    CLI->>Init: initCommand(serviceName, options)
    Init->>Registry: isValidRuntime(runtime)
    Registry-->>Init: ✓ valid
    Init->>Registry: getRuntimeConfig(runtime)
    Config->>Registry: Load plugin & resolve version
    Registry-->>Init: RuntimeConfig {defaultEntry, plugin, ...}
    Init->>FS: Write service.yaml with entry
    Init->>FS: Write package.json with entry
    Init->>FS: Write index.ts/js (based on entry type)
    FS-->>Init: ✓ Files created
    Init-->>CLI: ✓ Service initialized

Loading

sequenceDiagram
    participant CLI
    participant Lock as lock Command
    participant Env as Environment Module
    participant Registry as Runtime Registry
    participant FS as File System
    
    CLI->>Lock: lockCommand(servicePath, options)
    Lock->>Env: checkEnvironmentDrift(servicePath, runtime)
    Env->>Registry: getRuntimeConfig(runtime)
    Env->>FS: Load package.json, lock files
    Env->>Env: Hash dependencies, detect lockfile
    Env-->>Lock: EnvironmentInfo {isLocked, isDrift, ...}
    alt --check flag
        Lock->>CLI: Print drift info & exit
    else proceed to lock
        Lock->>Env: createEnvironmentManifest(servicePath, runtime)
        Env->>Env: Parse runtime, resolve version, hash files
        Env-->>Lock: EnvironmentManifest
        Lock->>Env: saveEnvironmentManifest(servicePath, manifest)
        Env->>FS: Write ignite.lock (YAML)
        FS-->>Lock: ✓ Locked
        Lock-->>CLI: ✓ Environment locked
    end

Loading

sequenceDiagram
    participant CLI
    participant Env as env Command
    participant Registry as Runtime Registry
    participant Plugin as Runtime Plugin
    participant FS as File System
    
    CLI->>Env: envCommand(servicePath, options)
    alt --runtimes flag
        Env->>Registry: listRuntimes()
        Registry->>Plugin: Fetch BUILTIN_RUNTIMES
        Plugin-->>Registry: {bun, node, deno, quickjs, versions, ...}
        Registry-->>Env: Format runtimes list
        Env-->>CLI: Print supported runtimes & examples
    else service info
        Env->>FS: Load service.yaml
        Env->>Env: checkEnvironmentDrift(servicePath, runtime)
        Env-->>CLI: Print service, runtime, drift status
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat(execution): add Docker-based execution engine #3: Directly related through Docker execution refactoring — both PRs modify packages/core/src/execution/* and docker-execution tests to support dynamic Dockerfile generation and runtime configuration changes.
• feat(core): add service loader and runtime registry #1: Directly related through runtime and service loading surface changes — both PRs modify runtime registry, service loader, Docker utilities, and core public API exports.

Poem

🐰 Bun hops forth as the default steed,
While Node, Deno, and QuickJS fulfill each need;
Plugins generate Dockerfiles with flair,
Lock files track drift with utmost care,
New CLI commands make the workflow so fair! 🎉

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}