@undefineds.co/xpod 0.2.0 → 0.2.1

package/README.md

@@ -1,92 +1,138 @@
 # Xpod: The Agent OS
 
-**Xpod is the Semantic File System for AI Agents.**
+Xpod is a **local-first Pod runtime for agents**.
 
-As explored in recent research (Manus, Claude Code, AGFS), the most effective interface for Agents is not a complex set of APIs, but a **File System**.
+It turns a Solid Pod into a runtime surface for data, identity, memory, sidecar capabilities, and AI APIs, all exposed through stable web interfaces.
 
-Following the Unix philosophy of *"Everything is a file"*, Xpod abstracts the complex world into a unified resource hierarchy accessible via standard protocols (HTTP/Solid).
+Xpod is the runtime itself. Internally it is built from Community Solid Server plus an API layer behind one gateway, but those are implementation details, not separate product boundaries.
 
-This is achieved through **Pods** (Personal Online Data stores)—portable web containers that act like a **"USB Drive for your Agent"**. A Pod encapsulates an Agent's entire digital life: its identity, memory, and skills.
+## What Xpod Provides
 
-**Xpod comes with a built-in Base Agent** that runs natively within this environment, ready to navigate, read, and execute Skills out of the box.
+- **Pod-native runtime**: a Pod is not only storage, but the runtime envelope around identity, memory, tools, and sessions
+- **Standard web surface**: HTTP, Solid, linked data, and stable URLs are the native interface
+- **Local-first execution**: agents run near user-owned data instead of pushing everything into remote app silos
+- **Multiple runtime shapes**: embed Xpod as a library, run it as a localhost service, or deploy it in the cloud
+- **AI-ready services**: sidecar APIs and OpenAI-compatible APIs are available on the same runtime surface
 
-## Installation
+## Runtime Shapes
 
-Ensure you have [Node.js 22.x LTS](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) installed:
+### Embedded runtime
+
+Start the full Xpod stack inside your own process.
+
+This is the lightest mode for CI, integration tests, and app-embedded scenarios. On Unix, Xpod can run over a local socket, so no TCP port is required.
+
+### Local daemon
+
+Run Xpod as a localhost HTTP service for a desktop app, tray process, or multiple local apps on the same machine.
+
+In this shape, Xpod is still the same runtime, just exposed over `127.0.0.1` so external processes can connect to it.
+
+### Cloud deployment
+
+Run Xpod as a hosted multi-user runtime with production dependencies such as PostgreSQL, Redis, and MinIO.
+
+This shape is suitable for managed Pod hosting, quota enforcement, and cloud-edge coordination.
+
+## Interfaces
+
+### Pod and Solid surface
+
+Xpod extends Community Solid Server and keeps Pod resources, WebID identity, and access control at the core.
+
+### Sidecar APIs
+
+Xpod exposes runtime capabilities alongside Pod resources through sidecar paths such as:
+
+- `/-/sparql`
+- `/-/vector`
+- `/-/terminal` (planned)
+
+### AI APIs
+
+Xpod also exposes AI-facing APIs for apps and agents, including:
+
+- `/v1/chat/completions`
+- `/v1/responses`
+- `/v1/messages`
+- `/v1/models`
+- `/v1/chatkit`
+
+## Deployment Profiles
+
+### `local`
+
+Best for personal use, development, local agents, and app integration.
+
+- SQLite + local disk
+- no Redis or MinIO required
+- good fit for embedded runtime and localhost daemon usage
+
+### `cloud`
+
+Best for hosted, multi-user, and production deployment.
+
+- PostgreSQL + MinIO + Redis
+- quota and usage infrastructure
+- node coordination, DNS, and reachability support
+
+See `docs/deployment-modes.md` for more detail.
+
+## Quick Start
+
+### Requirements
+
+- Bun 1.3+
+- Node.js 22+
+
+If you are building from source, Bun is the main package manager and task runner. If you are only consuming the published npm package, Node is still enough at runtime.
+
+### Install
 
 ```bash
-yarn install
-yarn build
+bun install
+bun run build
 ```
 
-> **Node runtime note**
-> Xpod currently targets Node 22 (`>=22 <23`). `.nvmrc` only declares the version; it does not force non-interactive runners to switch automatically.
-> AI/Codex runtimes, IDE background tasks, CI shells, or tmux panes may still start with the wrong `node` on `PATH`.
->
-> Before running installs, local startup, or integration tests, run:
->
-> ```bash
-> nvm use
-> yarn check:abi
-> ```
->
-> If you hit `better-sqlite3` / `NODE_MODULE_VERSION` errors, reinstall native dependencies under the same Node major:
->
-> ```bash
-> nvm use
-> yarn install --force --ignore-engines
-> ```
-
-
-## Single-File Build & Local npm Release
-
-- Build a single-file CLI entry (Node 22 target):
-  ```bash
-  yarn build:single
-  ```
-  Output: `dist/xpod.single.cjs` (also exposed as `xpod-single` in `bin`).
-
-- Create a local-tag npm publish (auto bumps to `-local.<timestamp>`):
-  ```bash
-  yarn publish:local
-  ```
-
-- Dry-run publish (no real upload, package.json auto-restored):
-  ```bash
-  yarn publish:local:dry
-  ```
-
-- Publish stable release (`latest` tag by default):
-  ```bash
-  yarn publish:release
-  ```
-
-- Dry-run stable release publish:
-  ```bash
-  yarn publish:release:dry
-  ```
+### ABI note
 
-## Quick Start
+Xpod currently expects Node in `>=22 <27` for Node-based runtime and packaging paths. `.nvmrc` helps humans, but non-interactive shells, IDE tasks, AI runtimes, or CI subprocesses may still pick the wrong `node` from `PATH`.
+
+Before local startup or integration tests, run:
+
+```bash
+nvm use
+bun run check:abi
+```
 
-| Mode | Command | Description |
-| --- | --- | --- |
-| Local | `yarn local` | SQLite + local disk, no external dependencies |
-| Cloud | `yarn cloud` | PostgreSQL + MinIO + Redis, production ready |
-| Dev | `yarn dev` | Alias for local mode |
+If you hit native module or `NODE_MODULE_VERSION` errors, reinstall dependencies under the same Node major:
 
-Configure environment:
 ```bash
-cp example.env .env.local     # For local/dev
-cp example.env .env.cloud     # For cloud/production
+nvm use
+bun install --force
 ```
 
-Visit [http://localhost:3000/](http://localhost:3000/) after startup.
+### Run locally
 
-See [docs/deployment-modes.md](docs/deployment-modes.md) for detailed profile comparison and cloud-edge coordination.
+```bash
+cp example.env .env.local
+bun run local
+```
+
+Visit `http://localhost:3000/` after startup.
 
-## Library Mode for Tests
+### Run in cloud mode
 
-If you want to start the full Xpod stack inside your test process, you can import it as a library instead of spawning the CLI.
+```bash
+cp example.env .env.cloud
+bun run cloud
+```
+
+## Library Mode
+
+If you want the full Xpod stack inside your own process, import it as a library instead of spawning the CLI.
+
+### In-process runtime without a TCP port
 
 ```ts
 import { startXpodRuntime } from '@undefineds.co/xpod/runtime';
@@ -103,7 +149,11 @@ console.log(await res.json());
 await runtime.stop();
 ```
 
-For the lightest test setup, use the test helper export:
+On Unix, `transport: 'socket'` keeps the full Xpod runtime in-process without binding a TCP port. This is the preferred shape for CI and integration tests.
+
+Use `open`, `authMode`, `apiOpen`, and related runtime options to tune authentication behavior for tests or embedded app flows.
+
+### No-auth test helper
 
 ```ts
 import { startNoAuthXpod } from '@undefineds.co/xpod/test-utils';
@@ -113,29 +163,22 @@ console.log(xpod.baseUrl);
 await xpod.stop();
 ```
 
-Notes:
-- In socket mode, the logical base URL is `http://localhost/`, but real traffic goes through a Unix socket.
-- This mode is ideal for CI and integration tests that should avoid external port conflicts.
-- Docker/full integration tests should still use real service startup.
+This helper is the lightest downstream path for integration tests that only need an open local stack.
 
 ### Using Xpod from a downstream project
 
-Install Xpod as a dev dependency in your test project:
+Install Xpod as a dev dependency:
 
 ```bash
-yarn add -D @undefineds.co/xpod
+bun add -d @undefineds.co/xpod
 ```
 
-Important for downstream CI / agent runners:
-- Run the parent toolchain with Node 22 as well. If Codex, IDE tasks, or other AI runtimes are launched under Node 23, they may ignore your directory-level `nvm` hook and still load the wrong native ABI.
-- The package ships `yarn check:abi`; use it before startup when debugging local environment issues.
-
 Recommended entry points:
-- `@undefineds.co/xpod` — CSS/components main entry
-- `@undefineds.co/xpod/runtime` — in-process runtime API (`startXpodRuntime`)
+
+- `@undefineds.co/xpod/runtime` — full runtime API (`startXpodRuntime`)
 - `@undefineds.co/xpod/test-utils` — lightest no-auth helper (`startNoAuthXpod`)
 
-A minimal `vitest` example in a downstream repo:
+A minimal `vitest` example:
 
 ```ts
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
@@ -143,14 +186,14 @@ import { startNoAuthXpod } from '@undefineds.co/xpod/test-utils';
 
 let xpod: Awaited<ReturnType<typeof startNoAuthXpod>>;
 
-afterAll(async() => {
-  await xpod?.stop();
-});
-
 beforeAll(async() => {
   xpod = await startNoAuthXpod();
 }, 60_000);
 
+afterAll(async() => {
+  await xpod?.stop();
+});
+
 describe('xpod integration', () => {
   it('starts in-process', async() => {
     const response = await fetch(new URL('/service/status', xpod.baseUrl));
@@ -159,177 +202,100 @@ describe('xpod integration', () => {
 });
 ```
 
-If you need more control in a downstream repo, use `startXpodRuntime` directly:
+Keep Docker/full integration tests on real services. Use library mode for lite and app-embedded test paths.
+
+### Localhost gateway for external apps
 
 ```ts
 import { startXpodRuntime } from '@undefineds.co/xpod/runtime';
 
 const runtime = await startXpodRuntime({
   mode: 'local',
-  open: true,
   transport: 'socket',
-  runtimeRoot: './.test-data/xpod-runtime',
+  bindHost: '127.0.0.1',
+  baseUrl: 'http://127.0.0.1:5710/',
+  gatewayPort: 5710,
 });
 
-// use runtime.baseUrl / runtime.fetch / runtime.sockets here
-await runtime.stop();
+console.log(runtime.baseUrl); // http://127.0.0.1:5710/
+```
+
+Use this shape when Xpod needs to behave as a shared local service. External apps connect over HTTP to the localhost gateway, while internal CSS/API traffic stays on Unix sockets.
+
+If Unix sockets are unavailable, switch to `transport: 'port'` to run the internal services on TCP ports too.
+
+## Testing
+
+```bash
+bun run test:integration:lite
+bun run test:integration:full
+bun run test:bun:runtime
 ```
 
-Typical downstream use cases:
-- Use `startNoAuthXpod()` for CI-friendly integration tests that only need an open local stack.
-- Use `startXpodRuntime()` when you need auth mode, custom storage paths, or explicit runtime options.
-- Keep Docker/cluster tests on real services; use library mode for local/lite test paths.
+- `test:integration:lite` starts Xpod in-process and runs the light integration path
+- `test:integration:full` keeps the real service stack for PostgreSQL / Redis / MinIO dependent paths
+- `test:bun:runtime` is the Bun runtime smoke gate
 
 ## Single-File Packaging
 
-Build a self-extracting single-file launcher:
+### Node launcher
+
+Build a self-extracting launcher:
 
 ```bash
-yarn build:single:standalone
+bun run build:single:standalone
 ```
 
-Output file: `dist/xpod-single.cjs`
+Output file:
 
-Run it directly (requires Node.js):
+- `.artifacts/xpod-single.cjs`
+
+Run it directly with Node:
 
 ```bash
-node dist/xpod-single.cjs --mode local
+node .artifacts/xpod-single.cjs --mode local
 ```
 
-On first start, it extracts runtime files to cache (default `~/.xpod/single-file-cache/`; override with `XPOD_SINGLE_CACHE_DIR`) and reuses that cache on subsequent launches.
+### Bun native binary
 
-## Deployment Strategies
-
-Xpod supports two primary deployment models, functioning like a Personal OS or a Multi-User Mainframe:
-
-1.  **Self-Hosted (Personal OS)**: Run Xpod on your laptop (`yarn local`) or private server. You have exclusive control over the hardware and kernel. Ideal for personal agents and maximum privacy.
-2.  **Managed Hosting (Multi-User OS)**: Deploy Xpod as a shared server (`yarn cloud`) hosting thousands of Pods. Similar to a Unix mainframe with many users (`/home/alice`, `/home/bob`), Xpod strictly enforces isolation between Pods using WebIDs and ACLs. Users share infrastructure but retain ownership of their data and can migrate their Pods to other instances.
-
-## The "Everything is a Resource" Architecture
-
-Xpod **leverages** the **W3C Solid Protocol** to construct a comprehensive **Runtime Environment for Agents**:
-
-### 1. File System as Memory
-Instead of opaque bytes, Xpod's file system is **Semantic**.
-- **Memory vs Context**: The entire Pod is your **Memory** (Total Knowledge). When an Agent enters a folder (e.g., `/projects/xpod/`), that folder becomes its **Context**. Navigating the file system naturally switches the Agent's attention scope.
-- **Universal Context**: In traditional systems, data is locked in proprietary formats. In Xpod, all data (Emails, Tasks, Notes) is stored in **RDF**—a universal data model. This allows Agents to understand and link data from any source without custom parsers.
-- **Universal Interface**: One protocol to rule them all. Agents use standard HTTP methods (`GET`, `PUT`, `DELETE`) to access everything—Memory, Files, Skills, and I/O. This drastically simplifies Agent design, as they don't need to learn thousands of different APIs.
-- **Smarter Agents**: Because Context is universally understood and accessible via a single protocol, Agents have a holistic view of your life and can connect dots between different domains effortlessly, leading to unprecedented intelligence.
-
-### 2. Identity as Path (`/profile/card#me`)
-Identity is not a database row, but a **URI**.
-- **WebID**: Every Agent has a globally unique ID (e.g., `https://pod.xpod.io/agent-alice/profile#me`).
-- **Access Control (ACL)**: Permissions are managed like file system attributes (Read/Write/Control), but applied to web resources.
-
-### 3. Virtual Resources (Dynamic Context)
-Not all resources are static files. Xpod supports **Virtual Resources** where the path is a key to a dynamic strategy.
-- **Implicit Graphs as Folders**: A path like `/threads/{id}/` or `/-/search?q=Entity` may not exist on disk. instead, it dynamically aggregates related messages via graph or vector retrieval, presenting them as a folder.
-- **API as File**: External capabilities are mapped to paths. Reading `/weather/current` triggers an API call; writing to `/inbox/` triggers a message delivery pipeline.
-- **Benefit**: Agents interact with complex, dynamic systems using the same simple file operations (`GET`/`PUT`) used for static memory.
-
-### 4. Security as Attributes (`chmod`)
-Xpod implements a fine-grained permission model tailored for Agents.
-- **WAC/ACP**: Access Control Lists (ACLs) determine which Agent (WebID) can Read, Write, or Append to any resource.
-- **Trust Chains**: Agents can form groups and delegate permissions, enabling secure multi-agent collaboration.
-
-### 5. Terminal & Skills (`/bin/*`)
-Xpod provides the runtime interfaces for Agent execution and interaction.
-- **`/-/terminal`** (Roadmap): A resource-based console. Agents listen to `/agents/{id}/stdin` and write to `/agents/{id}/stdout`, enabling interaction purely through file operations.
-- **Skills (Composable Capabilities)**: Xpod is the ideal runtime for Skills, enabling them to be:
-    - **Composable**: Skills interact via the standardized file system. The output of one Agent (an RDF graph or file) is immediately available as input for another.
-    - **Portable**: Built on Web Standards (JS/WASM + Markdown), Skills run consistently across Local, Server, or Edge Xpod instances.
-    - **Efficient**: Xpod's RDF indexing allows Skills to retrieve precise facts without loading massive files into the Context Window.
-    - **Powerful**: Unlike cloud agents trapped in sandboxes, Xpod Skills have **Root Access** to your digital life. They can access your full history, local files, and private devices, acting as a true Digital Butler rather than just a Chatbot.
-
-### 6. Network & Federation (Cloud-Edge Architecture)
-Xpod introduces a robust distributed architecture on top of standard Solid protocols.
-- **Control Plane (The Cloud)**: The Xpod Server acts as a coordinator, providing DNS, TLS certificates, and Tunneling services. It ensures your Agent is discoverable and reachable from the global internet.
-- **Data Plane (The Edge)**: Your Local Xpod holds the actual data and runs the Agents. It connects to the Cloud for reachability but executes Skills locally, ensuring data never leaves your physical control.
-
-### 7. Dual-Process Architecture (CSS + API Server)
-
-Xpod runs as two cooperating processes behind a single gateway:
-
-| Process | Port | Responsibility |
-|---------|------|----------------|
-| **CSS** (Solid Server) | 3000 | LDP resource access, OIDC auth, SPARQL, WebSocket notifications |
-| **API Server** | 3001 | Node management, heartbeat/DNS sync, quota, API Keys, AI chat |
-
-- **CSS** handles everything related to the Solid protocol — it's the kernel of the Pod file system.
-- **API Server** handles management APIs that don't belong in the Solid request chain.
-- Both share the same PostgreSQL database (server mode) or SQLite (local mode).
-
-**Auth methods**: Solid Token (DPoP/Bearer), API Key (`sk-*`), Node Token (`XpodNode nodeId:token`).
-
-**API Server routes**:
-
-| Route | Description | Mode |
-|-------|-------------|------|
-| `POST /v1/signal` | Edge node heartbeat → health check → DNS sync | Shared |
-| `/v1/nodes/*` | Node CRUD | Shared |
-| `/v1/keys/*` | API Key management | Shared |
-| `/v1/chat/completions` | OpenAI-compatible chat (SSE streaming) | Shared |
-| `/v1/responses` | OpenAI Responses API | Shared |
-| `/v1/messages` | Anthropic/OpenAI Threads compatible | Shared |
-| `/v1/models` | List available models | Shared |
-| `POST /v1/chatkit` | ChatKit protocol endpoint (streaming) | Shared |
-| `/v1/chatkit/threads/*` | ChatKit REST API (threads CRUD, items) | Shared |
-| `/v1/subdomains/*` | Subdomain allocation | Cloud |
-| `/v1/ddns/*` | Dynamic DNS management | Cloud |
-| `/v1/webid-profile/*` | WebID Profile hosting | Cloud |
-| `/provision/nodes` | SP registration | Cloud |
-| `/provision/pods` | Pod creation (SP callback) | Local |
-| `/admin/*` | Local config & restart | Local |
-
-Key components:
-- `EdgeNodeSignalHandler` (API Server) — receives heartbeats, triggers health checks and DNS synchronization
-- `EdgeNodeSignalClient` (local/edge) — sends periodic heartbeats with system metrics, network info, and tunnel status
-
-## Privacy & Compliance (GDPR)
-
-Xpod is designed for the post-GDPR world, where **Data Sovereignty** is paramount.
-
-- **Data Ownership**: Unlike SaaS platforms where data is locked in silos, Xpod stores data in **User-Owned Pods**. You physically possess your data (on your disk or your chosen server).
-- **Code Moves to Data**: Computation happens **locally** next to the data. This "Local-First" architecture minimizes data leakage and cross-border transfer risks.
-- **Granular Consent**: WAC/ACP Access Control Lists allow users to grant Agents access only to specific resources (e.g., "Read `/photos/` but not `/documents/`").
-- **Right to be Forgotten**: Deleting a resource in Xpod is a true physical deletion, ensuring compliance with erasure requests.
-
-## Roadmap
-
-- [x] DB-Based Identity Provider
-- [x] Fine-Grained Pod Capacity Management
-- [x] SPARQL 1.1 via LDP (sparql-update)
-- [x] Sidecar API: SPARQL (`/-/sparql`)
-- [x] Sidecar API: Vector (`/-/vector`)
-- [x] Cloud-Edge Cluster Architecture
-- [x] API Server (dual-process architecture, separated from CSS)
-- [x] Multi-Auth: Solid Token / API Key / Node Token
-- [x] Edge Node Heartbeat + Health Check + DNS Sync
-- [x] SP Provision & Pod Management
-- [x] AI API: Chat Completions, Responses, Messages, Models (OpenAI-compatible, SSE streaming)
-- [x] ChatKit API (conversation management)
-- [x] Subdomain & DDNS Management
-- [ ] Sidecar API: Terminal (`/-/terminal`)
-- [ ] Rate Limiting
-- [ ] Attribute-Based Access Control (ABAC)
-- [ ] Feature Store (Federated Learning)
+Build the Bun single-file binary:
 
-## Documentation
+```bash
+bun run build:single:bun
+```
+
+Output file:
 
-- [docs/COMPONENTS.md](docs/COMPONENTS.md) - Components.js reference and configuration patterns
-- [docs/api-service-design.md](docs/api-service-design.md) - API Server architecture, routes, and auth design
-- [docs/deployment-modes.md](docs/deployment-modes.md) - Deployment profiles (local, cloud)
-- [docs/admin-guide.md](docs/admin-guide.md) - Admin initialization, roles, and reserved names
-- [docs/edge-cluster-architecture.md](docs/edge-cluster-architecture.md) - Cloud-edge coordination and routing
-- [docs/edge-node-deployment-modes.md](docs/edge-node-deployment-modes.md) - Edge node deployment scenarios
-- [docs/sidecar-api.md](docs/sidecar-api.md) - Sidecar API pattern (`/-/{service}`)
-- [docs/sparql-support.md](docs/sparql-support.md) - SPARQL 1.1 support details
-- [docs/vector-api-server-guide.md](docs/vector-api-server-guide.md) - Vector search API guide
+- `dist/xpod-bun`
 
-## Contributing
+Run it directly:
 
-Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) to understand how to contribute to the project.
+```bash
+dist/xpod-bun --mode local --port 5710
+```
+
+On supported Unix platforms, `npm install @undefineds.co/xpod` can also resolve a matching optional platform package for the native `xpod` binary.
+
+## Architecture at a Glance
+
+Xpod is one runtime with a unified gateway and several internal planes:
 
-## License
+- **Pod / data plane**: Pod resources, RDF storage, access control, and standard Solid handling
+- **API / control plane**: AI-facing APIs, admin APIs, sidecar capabilities, and coordination services
+- **Agent runtime plane**: sessions, tasks, tool access, and long-running agent behavior near the Pod
+
+In implementation terms, CSS and the API service are internal parts of Xpod's runtime.
+
+## Typical Use Cases
+
+- **Personal Agent OS**: run your own AI-native Pod locally with your data, memory, and tools
+- **Desktop or local app backend**: expose one localhost runtime that multiple apps can share
+- **Backend for AI-native Solid apps**: combine Pod-native data, identity, and AI services in one runtime
+- **Managed Pod platform**: host many users on shared infrastructure while preserving Pod isolation
+
+## Documentation
 
-Xpod is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+- `docs/deployment-modes.md` — local vs cloud deployment
+- `docs/architecture.md` — system architecture overview
+- `docs/COMPONENTS.md` — component overrides and architecture extensions
+- `docs/sidecar-api.md` — sidecar API patterns

package/bin/xpod.js

@@ -1,2 +1,91 @@
 #!/usr/bin/env node
-require('../dist/cli/index.js');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+function detectLinuxLibc() {
+  if (process.platform !== 'linux') {
+    return undefined;
+  }
+
+  const report = process.report?.getReport?.();
+  if (report?.header?.glibcVersionRuntime) {
+    return 'glibc';
+  }
+
+  return 'musl';
+}
+
+function getBinaryPackageCandidates() {
+  if (process.platform === 'darwin') {
+    if (process.arch === 'arm64' || process.arch === 'x64') {
+      return [ `@undefineds.co/xpod-darwin-${process.arch}` ];
+    }
+    return [];
+  }
+
+  if (process.platform === 'linux') {
+    const libc = detectLinuxLibc() === 'musl' ? 'musl' : 'gnu';
+    if (process.arch === 'arm64' || process.arch === 'x64') {
+      return [ `@undefineds.co/xpod-linux-${process.arch}-${libc}` ];
+    }
+  }
+
+  return [];
+}
+
+function resolveBinary() {
+  for (const packageName of getBinaryPackageCandidates()) {
+    try {
+      const packageJsonPath = require.resolve(`${packageName}/package.json`);
+      const packageRoot = path.dirname(packageJsonPath);
+      const packageJson = require(packageJsonPath);
+      const binaryRelativePath = packageJson.xpodBinary || './xpod';
+      return path.join(packageRoot, binaryRelativePath);
+    } catch {
+      // Try next candidate.
+    }
+  }
+
+  return undefined;
+}
+
+function runJsCli() {
+  require('../dist/cli/index.js');
+}
+
+function main() {
+  if (process.env.XPOD_PREFER_JS_CLI === 'true') {
+    runJsCli();
+    return;
+  }
+
+  const binaryPath = resolveBinary();
+  if (!binaryPath) {
+    runJsCli();
+    return;
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  child.once('error', () => runJsCli());
+  child.once('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  detectLinuxLibc,
+  getBinaryPackageCandidates,
+  resolveBinary,
+};

package/config/bun.json

@@ -12,7 +12,7 @@
   ],
   "@graph": [
     {
-      "comment": "Bun runtime profile - uses BunQuintStore and BunVectorStore instead of better-sqlite3 based stores",
+      "comment": "Bun runtime profile - uses BunQuintStore and BunVectorStore instead of Node SQLite stores",
       "@id": "urn:undefineds:xpod:QuintStore",
       "@type": "BunQuintStore",
       "path": {

package/config/cli.json

@@ -105,6 +105,7 @@
           "name": "redisUsername",
           "options": {
             "type": "string",
+            "default": "",
             "hidden": true
           }
         },
@@ -113,6 +114,7 @@
           "name": "redisPassword",
           "options": {
             "type": "string",
+            "default": "",
             "hidden": true
           }
         },
@@ -121,6 +123,7 @@
           "name": "emailConfigHost",
           "options": {
             "type": "string",
+            "default": "",
             "hidden": true
           }
         },
@@ -129,6 +132,7 @@
           "name": "emailConfigPort",
           "options": {
             "type": "number",
+            "default": 587,
             "hidden": true
           }
         },
@@ -137,6 +141,7 @@
           "name": "emailConfigAuthUser",
           "options": {
             "type": "string",
+            "default": "",
             "hidden": true
           }
         },

package/config/test.local.json

@@ -0,0 +1,6 @@
+{
+  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld",
+  "import": [
+    "css:config/file.json"
+  ]
+}