deltabox-lite 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# deltabox-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package installs the native `deltabox` runtime for supported Linux and
+macOS systems. The matching optional platform package carries the binary and
+the Node-API addon; `bin/deltabox.js` is a thin launcher that executes that
+binary in place, so `npm install --global deltabox-lite` puts a `deltabox`
+command on the PATH. No prestarted service is installed.
+
+```js
+const { binaryPath, loadNative } = require('deltabox-lite')
+const { NativeDeltabox } = loadNative()
+const runtime = new NativeDeltabox(process.cwd(), binaryPath(), {
+  fsMode: 'cbcow-through',
+  isolation: 'deltabox',
+})
+```
+
+Native methods return promises backed by the addon's Tokio blocking runtime.
+The coordinator and active filesystem state stay resident in the Node process;
+storage mode and command isolation are fixed at construction. The default
+`cbcow-through` + `deltabox` pair runs commands under the session's own sandbox
+and deny set, which is why `isolation: 'none'` has to be asked for by name:
+those commands share the Node process ambient environment instead. File reads
+and writes use `Buffer`, while session, checkpoint, diff, commit, abort, and
+review calls return protocol-shaped typed objects. Every session record names
+its `isolation` profile and the resolved `isolation_provider` (`sandlock` or
+`seatbelt`).
+
+Linux CB-CoW modes require `/dev/fuse` and `fusermount3` or `fusermount` on the
+host. Deltabox otherwise reports the reason and falls back to `copy-private`
+unless the requested mode is required.
+
+See the [deltabox-lite repository](https://github.com/delta-box/deltabox-lite)
+for usage and policy documentation.

package/bin/deltabox.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Launcher for the `deltabox` command. The real binary ships in the
+// platform-specific optional dependency; npm only links the bins that the
+// top-level package declares, so a global install of `deltabox-lite` gets
+// its command from this shim rather than from the platform package.
+//
+// The child runs with inherited stdio (so `deltabox serve` can speak
+// JSON-RPC over the launcher's own stdin/stdout), termination signals sent to
+// the launcher are forwarded to it, and its exit status is mirrored.
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { constants } = require("node:os");
+
+let binary;
+try {
+  binary = require("../index.cjs").binaryPath();
+} catch (error) {
+  process.stderr.write(
+    `deltabox-lite: cannot locate the deltabox binary for this platform.\n` +
+      `${error.message}\n` +
+      `Reinstall with optional dependencies enabled (npm install --include=optional).\n`,
+  );
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+// A supervisor that signals only the launcher (rather than the whole
+// process group) must still stop the real deltabox, so relay termination
+// signals instead of dying and leaving the child orphaned.
+const relayed = ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of relayed) {
+  process.on(signal, () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  });
+}
+
+child.on("error", (error) => {
+  process.stderr.write(`deltabox-lite: failed to launch ${binary}: ${error.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Mirror the child's termination: raise the same signal on ourselves with
+    // the default disposition restored. Signals Node ignores (SIGPIPE) cannot
+    // terminate us that way, so fall back to the shell convention 128+n.
+    for (const relayedSignal of relayed) process.removeAllListeners(relayedSignal);
+    const number = constants.signals[signal];
+    process.exitCode = number ? 128 + number : 1;
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      // Unknown signal name: the fallback exit code above applies.
+    }
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/index.cjs

@@ -0,0 +1,28 @@
+const { dirname, join } = require("node:path");
+
+const packages = {
+  "darwin-arm64": "deltabox-lite-darwin-arm64",
+  "darwin-x64": "deltabox-lite-darwin-x64",
+  "linux-arm64": "deltabox-lite-linux-arm64",
+  "linux-x64": "deltabox-lite-linux-x64",
+};
+
+function platformPackageRoot() {
+  const name = packages[`${process.platform}-${process.arch}`];
+  if (!name) throw new Error(`deltabox-lite does not support ${process.platform}/${process.arch}`);
+  return dirname(require.resolve(`${name}/package.json`));
+}
+
+function binaryPath() {
+  return join(platformPackageRoot(), "bin", "deltabox");
+}
+
+function nativePath() {
+  return join(platformPackageRoot(), "native", "deltabox.node");
+}
+
+function loadNative() {
+  return require(nativePath());
+}
+
+module.exports = { binaryPath, nativePath, loadNative };

package/index.d.ts

@@ -0,0 +1,161 @@
+/// <reference types="node" />
+
+export interface NativeEnvironmentEntry {
+  key: string
+  value: string
+}
+
+/**
+ * Configuration snapshot for one embedded coordinator, fixed at construction.
+ * `fsMode` is the storage mode every session on this coordinator starts in;
+ * `isolation` picks how commands run. Neither can be changed later, because the
+ * coordinator and its active filesystem state live for the whole process.
+ */
+export interface NativeDeltaboxOptions {
+  stateDir?: string
+  runtimeDir?: string
+  fsMode?: 'cbcow-through' | 'cbcow-private' | 'copy-private'
+  /**
+   * `deltabox` keeps the session's own sandbox and deny set. `none` lets
+   * commands share the Node process ambient environment, so a host has to name
+   * it explicitly; the native transport is the only one that can offer it.
+   */
+  isolation?: 'deltabox' | 'none'
+}
+
+export interface NativeSessionInfo {
+  session_id: string
+  project: string
+  started_at_ms: number
+  status: 'running' | 'stopped'
+  checkpoint_count: number
+  pending_changes: number
+  requested_fs_mode: 'cbcow-through' | 'cbcow-private' | 'copy-private'
+  resolved_fs_mode: 'cbcow-through' | 'cbcow-private' | 'copy-private'
+  host_visibility: 'immediate' | 'on-commit'
+  durability: string
+  group_commit_ms?: number
+  isolation: 'deltabox' | 'none'
+  /** Resolved OS mechanism behind `deltabox` isolation, absent under `none`. */
+  isolation_provider: string | null
+  state_provider: string | null
+  fallback_reason: string | null
+  rollback_guarantee: string
+  tainted: boolean
+  mountpoint?: string
+}
+
+export interface NativeExecResult {
+  exit_code: number | null
+  stdout: string
+  stderr: string
+  duration_ms: number
+  truncated: boolean
+}
+
+/**
+ * Filesystem breadth for one command. `workspace-write` (the default) keeps
+ * writes inside the session workspace; `read-write` additionally reaches the
+ * rest of the host filesystem while the workspace stays Deltabox-managed and
+ * the backing project stays denied.
+ */
+export type NativeExecutionProfile = 'workspace-write' | 'read-write'
+
+export interface NativeCheckpointInfo {
+  id: string
+  label: string | null
+  created_at_ms: number
+  change_count: number
+  committed: boolean
+}
+
+export interface NativeActiveReview {
+  checkpoint_id: string
+  kind: 'task' | 'tool' | 'risky'
+  label: string | null
+  started_at_ms: number
+}
+
+export interface NativeChange {
+  path: string
+  kind: 'added' | 'modified' | 'deleted'
+  old_size: number | null
+  new_size: number | null
+  is_binary: boolean
+  added_lines: number
+  removed_lines: number
+  text_diff?: string
+}
+
+export interface NativeDiffResult {
+  from: string | null
+  to: string | null
+  pending_changes: number
+  changes: NativeChange[]
+}
+
+export interface NativeCommitResult {
+  checkpoint_id: string
+  applied: number
+  /**
+   * How many sibling publications this commit's baseline was fast-forwarded
+   * over; absent when zero. When set, the host moved since this session's
+   * baseline and the orchestrator should re-verify (build, test) after
+   * integration.
+   */
+  folded_publications?: number
+}
+
+export interface NativeAbortResult {
+  checkpoint_id: string
+  restored: number
+}
+
+export interface NativeDeltaboxInstance {
+  startSession(
+    policy?: string,
+    durability?: 'fast' | 'strict',
+    groupCommitMs?: number,
+    filesystemMode?: 'auto' | 'cbcow-through' | 'cbcow-private' | 'copy-private',
+    requireFilesystemMode?: boolean,
+  ): Promise<NativeSessionInfo>
+  stopSession(sessionId: string): Promise<NativeSessionInfo>
+  sessionStatus(sessionId: string): Promise<NativeSessionInfo>
+  exec(
+    sessionId: string,
+    argv: string[],
+    cwd?: string,
+    environment?: NativeEnvironmentEntry[],
+    label?: string,
+    executionProfile?: NativeExecutionProfile,
+  ): Promise<NativeExecResult>
+  readFile(sessionId: string, path: string): Promise<Buffer>
+  writeFile(sessionId: string, path: string, content: Buffer): Promise<void>
+  recordFileChanges(sessionId: string, paths: string[]): Promise<void>
+  checkpoint(sessionId: string, label?: string): Promise<NativeCheckpointInfo>
+  diff(sessionId: string, from?: string, to?: string): Promise<NativeDiffResult>
+  commit(sessionId: string, checkpoint?: string): Promise<NativeCommitResult>
+  abort(sessionId: string, checkpoint?: string): Promise<NativeAbortResult>
+  beginReview(sessionId: string, kind: 'task' | 'tool' | 'risky', label?: string): Promise<NativeActiveReview>
+  reviewStatus(sessionId: string): Promise<NativeActiveReview | null>
+  reviewDiff(sessionId: string): Promise<NativeDiffResult>
+  reviewCommit(sessionId: string): Promise<NativeCommitResult>
+  reviewAbort(sessionId: string): Promise<NativeAbortResult>
+  reviewSkip(sessionId: string): Promise<NativeActiveReview>
+}
+
+export interface NativeDeltaboxConstructor {
+  new(
+    projectRoot: string,
+    helperBinary: string,
+    options?: NativeDeltaboxOptions,
+  ): NativeDeltaboxInstance
+}
+
+export interface DeltaboxNativeBinding {
+  NativeDeltabox: NativeDeltaboxConstructor
+}
+
+export function binaryPath(): string
+export function nativePath(): string
+export function loadNative(): DeltaboxNativeBinding

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "deltabox-lite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Native sandbox runtime with diff, commit, and abort for AI coding agents",
+  "repository": "https://github.com/delta-box/deltabox-lite",
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "bin": {
+    "deltabox": "bin/deltabox.js"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.cjs",
+    "index.d.ts",
+    "bin/deltabox.js",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "deltabox-lite-darwin-arm64": "0.1.0",
+    "deltabox-lite-darwin-x64": "0.1.0",
+    "deltabox-lite-linux-arm64": "0.1.0",
+    "deltabox-lite-linux-x64": "0.1.0"
+  }
+}