@opencode-cloud/core 0.1.0

package/Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "opencode-cloud-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+keywords.workspace = true
+categories.workspace = true
+description = "Core library for opencode-cloud - config management, singleton enforcement, and shared utilities"
+readme = "../../README.md"
+exclude = ["*.node", "index.js", "index.d.ts"]
+
+[lib]
+# Both crate types: cdylib for NAPI Node bindings, rlib for Rust CLI
+crate-type = ["cdylib", "rlib"]
+
+[features]
+default = []
+napi = ["dep:napi", "dep:napi-derive"]
+
+[dependencies]
+clap.workspace = true
+tokio.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+jsonc-parser.workspace = true
+directories.workspace = true
+thiserror.workspace = true
+anyhow.workspace = true
+tracing.workspace = true
+console.workspace = true
+
+# NAPI dependencies (optional - only for Node bindings)
+napi = { workspace = true, optional = true }
+napi-derive = { workspace = true, optional = true }
+
+[build-dependencies]
+napi-build = "2"
+
+[dev-dependencies]
+tempfile.workspace = true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Ryszkiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build.rs

@@ -0,0 +1,4 @@
+fn main() {
+    // Setup NAPI build for the cdylib target
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,14 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* NAPI-RS type definitions for @opencode-cloud/core */
+
+/**
+ * Get the version string for Node.js consumers
+ */
+export function getVersionJs(): string;
+
+/**
+ * Get the long version string with build info for Node.js consumers
+ */
+export function getVersionLongJs(): string;

package/index.js

@@ -0,0 +1,146 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* NAPI-RS bindings loader for @opencode-cloud/core */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'core.darwin-arm64.node'))
+    if (arch === 'arm64') {
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.darwin-arm64.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-darwin-arm64')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    } else {
+      localFileExisted = existsSync(join(__dirname, 'core.darwin-x64.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.darwin-x64.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-darwin-x64')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    }
+    break
+  case 'linux':
+    if (arch === 'x64') {
+      if (isMusl()) {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-x64-musl.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-x64-musl.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-x64-musl')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      } else {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-x64-gnu.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-x64-gnu.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-x64-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      }
+    } else if (arch === 'arm64') {
+      if (isMusl()) {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-arm64-musl.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-arm64-musl.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-arm64-musl')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      } else {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-arm64-gnu.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-arm64-gnu.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-arm64-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      }
+    }
+    break
+  case 'win32':
+    if (arch === 'x64') {
+      localFileExisted = existsSync(join(__dirname, 'core.win32-x64-msvc.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.win32-x64-msvc.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-win32-x64-msvc')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    } else if (arch === 'arm64') {
+      localFileExisted = existsSync(join(__dirname, 'core.win32-arm64-msvc.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.win32-arm64-msvc.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-win32-arm64-msvc')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { getVersionJs, getVersionLongJs } = nativeBinding
+
+module.exports.getVersionJs = getVersionJs
+module.exports.getVersionLongJs = getVersionLongJs

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@opencode-cloud/core",
+  "version": "0.1.0",
+  "description": "Core NAPI bindings for opencode-cloud (internal package)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "pRizz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pRizz/opencode-cloud.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/pRizz/opencode-cloud",
+  "bugs": {
+    "url": "https://github.com/pRizz/opencode-cloud/issues"
+  },
+  "keywords": [
+    "opencode",
+    "ai",
+    "cloud",
+    "napi",
+    "rust"
+  ],
+  "napi": {
+    "binaryName": "core",
+    "triples": {}
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0-alpha.69"
+  },
+  "scripts": {
+    "build": "napi build --platform --release --features napi --no-js && cp src/bindings.js index.js && cp src/bindings.d.ts index.d.ts",
+    "build:debug": "napi build --platform --features napi --no-js && cp src/bindings.js index.js && cp src/bindings.d.ts index.d.ts",
+    "postinstall": "npm run build || echo 'Build failed - ensure Rust 1.82+ is installed (rustup.rs)'"
+  }
+}

package/src/bindings.d.ts

@@ -0,0 +1,14 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* NAPI-RS type definitions for @opencode-cloud/core */
+
+/**
+ * Get the version string for Node.js consumers
+ */
+export function getVersionJs(): string;
+
+/**
+ * Get the long version string with build info for Node.js consumers
+ */
+export function getVersionLongJs(): string;

package/src/bindings.js

@@ -0,0 +1,146 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* NAPI-RS bindings loader for @opencode-cloud/core */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'core.darwin-arm64.node'))
+    if (arch === 'arm64') {
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.darwin-arm64.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-darwin-arm64')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    } else {
+      localFileExisted = existsSync(join(__dirname, 'core.darwin-x64.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.darwin-x64.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-darwin-x64')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    }
+    break
+  case 'linux':
+    if (arch === 'x64') {
+      if (isMusl()) {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-x64-musl.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-x64-musl.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-x64-musl')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      } else {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-x64-gnu.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-x64-gnu.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-x64-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      }
+    } else if (arch === 'arm64') {
+      if (isMusl()) {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-arm64-musl.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-arm64-musl.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-arm64-musl')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      } else {
+        localFileExisted = existsSync(join(__dirname, 'core.linux-arm64-gnu.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./core.linux-arm64-gnu.node')
+          } else {
+            nativeBinding = require('@opencode-cloud/core-linux-arm64-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+      }
+    }
+    break
+  case 'win32':
+    if (arch === 'x64') {
+      localFileExisted = existsSync(join(__dirname, 'core.win32-x64-msvc.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.win32-x64-msvc.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-win32-x64-msvc')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    } else if (arch === 'arm64') {
+      localFileExisted = existsSync(join(__dirname, 'core.win32-arm64-msvc.node'))
+      try {
+        if (localFileExisted) {
+          nativeBinding = require('./core.win32-arm64-msvc.node')
+        } else {
+          nativeBinding = require('@opencode-cloud/core-win32-arm64-msvc')
+        }
+      } catch (e) {
+        loadError = e
+      }
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { getVersionJs, getVersionLongJs } = nativeBinding
+
+module.exports.getVersionJs = getVersionJs
+module.exports.getVersionLongJs = getVersionLongJs

package/src/config/mod.rs

@@ -0,0 +1,165 @@
+//! Configuration management for opencode-cloud
+//!
+//! Handles loading, saving, and validating the JSONC configuration file.
+//! Creates default config if missing, validates against schema.
+
+pub mod paths;
+pub mod schema;
+
+use std::fs::{self, File};
+use std::io::{Read, Write};
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+use jsonc_parser::parse_to_serde_value;
+
+pub use paths::{get_config_dir, get_config_path, get_data_dir, get_pid_path};
+pub use schema::Config;
+
+/// Ensure the config directory exists
+///
+/// Creates `~/.config/opencode-cloud/` if it doesn't exist.
+/// Returns the path to the config directory.
+pub fn ensure_config_dir() -> Result<PathBuf> {
+    let config_dir =
+        get_config_dir().ok_or_else(|| anyhow::anyhow!("Could not determine config directory"))?;
+
+    if !config_dir.exists() {
+        fs::create_dir_all(&config_dir).with_context(|| {
+            format!(
+                "Failed to create config directory: {}",
+                config_dir.display()
+            )
+        })?;
+        tracing::info!("Created config directory: {}", config_dir.display());
+    }
+
+    Ok(config_dir)
+}
+
+/// Ensure the data directory exists
+///
+/// Creates `~/.local/share/opencode-cloud/` if it doesn't exist.
+/// Returns the path to the data directory.
+pub fn ensure_data_dir() -> Result<PathBuf> {
+    let data_dir =
+        get_data_dir().ok_or_else(|| anyhow::anyhow!("Could not determine data directory"))?;
+
+    if !data_dir.exists() {
+        fs::create_dir_all(&data_dir)
+            .with_context(|| format!("Failed to create data directory: {}", data_dir.display()))?;
+        tracing::info!("Created data directory: {}", data_dir.display());
+    }
+
+    Ok(data_dir)
+}
+
+/// Load configuration from the config file
+///
+/// If the config file doesn't exist, creates a new one with default values.
+/// Supports JSONC (JSON with comments).
+/// Rejects unknown fields for strict validation.
+pub fn load_config() -> Result<Config> {
+    let config_path =
+        get_config_path().ok_or_else(|| anyhow::anyhow!("Could not determine config file path"))?;
+
+    if !config_path.exists() {
+        // Create default config
+        tracing::info!(
+            "Config file not found, creating default at: {}",
+            config_path.display()
+        );
+        let config = Config::default();
+        save_config(&config)?;
+        return Ok(config);
+    }
+
+    // Read the file
+    let mut file = File::open(&config_path)
+        .with_context(|| format!("Failed to open config file: {}", config_path.display()))?;
+
+    let mut contents = String::new();
+    file.read_to_string(&mut contents)
+        .with_context(|| format!("Failed to read config file: {}", config_path.display()))?;
+
+    // Parse JSONC (JSON with comments)
+    let parsed_value = parse_to_serde_value(&contents, &Default::default())
+        .map_err(|e| anyhow::anyhow!("Invalid JSONC in config file: {}", e))?
+        .ok_or_else(|| anyhow::anyhow!("Config file is empty"))?;
+
+    // Deserialize into Config struct (deny_unknown_fields will reject unknown keys)
+    let config: Config = serde_json::from_value(parsed_value).with_context(|| {
+        format!(
+            "Invalid configuration in {}. Check for unknown fields or invalid values.",
+            config_path.display()
+        )
+    })?;
+
+    Ok(config)
+}
+
+/// Save configuration to the config file
+///
+/// Creates a backup of the existing config (config.json.bak) before overwriting.
+/// Ensures the config directory exists.
+pub fn save_config(config: &Config) -> Result<()> {
+    ensure_config_dir()?;
+
+    let config_path =
+        get_config_path().ok_or_else(|| anyhow::anyhow!("Could not determine config file path"))?;
+
+    // Create backup if file exists
+    if config_path.exists() {
+        let backup_path = config_path.with_extension("json.bak");
+        fs::copy(&config_path, &backup_path)
+            .with_context(|| format!("Failed to create backup at: {}", backup_path.display()))?;
+        tracing::debug!("Created config backup: {}", backup_path.display());
+    }
+
+    // Serialize with pretty formatting
+    let json = serde_json::to_string_pretty(config).context("Failed to serialize configuration")?;
+
+    // Write to file
+    let mut file = File::create(&config_path)
+        .with_context(|| format!("Failed to create config file: {}", config_path.display()))?;
+
+    file.write_all(json.as_bytes())
+        .with_context(|| format!("Failed to write config file: {}", config_path.display()))?;
+
+    tracing::debug!("Saved config to: {}", config_path.display());
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_path_resolution_returns_values() {
+        // Verify path functions return Some on supported platforms
+        assert!(get_config_dir().is_some());
+        assert!(get_data_dir().is_some());
+        assert!(get_config_path().is_some());
+        assert!(get_pid_path().is_some());
+    }
+
+    #[test]
+    fn test_paths_end_with_expected_names() {
+        let config_dir = get_config_dir().unwrap();
+        assert!(config_dir.ends_with("opencode-cloud"));
+
+        let data_dir = get_data_dir().unwrap();
+        assert!(data_dir.ends_with("opencode-cloud"));
+
+        let config_path = get_config_path().unwrap();
+        assert!(config_path.ends_with("config.json"));
+
+        let pid_path = get_pid_path().unwrap();
+        assert!(pid_path.ends_with("opencode-cloud.pid"));
+    }
+
+    // Note: Integration tests for load_config/save_config that modify the real
+    // filesystem are run via CLI commands rather than unit tests to avoid
+    // test isolation issues with environment variable manipulation in Rust 2024.
+}

package/src/config/paths.rs

@@ -0,0 +1,108 @@
+//! XDG-compliant path resolution for opencode-cloud
+//!
+//! Provides consistent path resolution across platforms:
+//! - Linux/macOS: ~/.config/opencode-cloud/ and ~/.local/share/opencode-cloud/
+//! - Windows: %APPDATA%\opencode-cloud\ and %LOCALAPPDATA%\opencode-cloud\
+
+use std::path::PathBuf;
+
+/// Get the configuration directory path
+///
+/// Returns the directory where config.json should be stored:
+/// - Linux: `~/.config/opencode-cloud/`
+/// - macOS: `~/.config/opencode-cloud/` (XDG-style, not ~/Library)
+/// - Windows: `%APPDATA%\opencode-cloud\`
+pub fn get_config_dir() -> Option<PathBuf> {
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    {
+        directories::BaseDirs::new()
+            .map(|dirs| dirs.home_dir().join(".config").join("opencode-cloud"))
+    }
+    #[cfg(target_os = "windows")]
+    {
+        directories::BaseDirs::new()
+            .and_then(|dirs| dirs.config_dir().map(|d| d.to_path_buf()))
+            .map(|d| d.join("opencode-cloud"))
+    }
+    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+    {
+        None
+    }
+}
+
+/// Get the data directory path
+///
+/// Returns the directory where runtime data (PID file, logs, etc.) should be stored:
+/// - Linux: `~/.local/share/opencode-cloud/`
+/// - macOS: `~/.local/share/opencode-cloud/` (XDG-style, not ~/Library)
+/// - Windows: `%LOCALAPPDATA%\opencode-cloud\`
+pub fn get_data_dir() -> Option<PathBuf> {
+    #[cfg(any(target_os = "linux", target_os = "macos"))]
+    {
+        directories::BaseDirs::new().map(|dirs| {
+            dirs.home_dir()
+                .join(".local")
+                .join("share")
+                .join("opencode-cloud")
+        })
+    }
+    #[cfg(target_os = "windows")]
+    {
+        directories::BaseDirs::new()
+            .and_then(|dirs| dirs.data_local_dir().map(|d| d.to_path_buf()))
+            .map(|d| d.join("opencode-cloud"))
+    }
+    #[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
+    {
+        None
+    }
+}
+
+/// Get the full path to the config file
+///
+/// Returns: `{config_dir}/config.json`
+pub fn get_config_path() -> Option<PathBuf> {
+    get_config_dir().map(|d| d.join("config.json"))
+}
+
+/// Get the full path to the PID lock file
+///
+/// Returns: `{data_dir}/opencode-cloud.pid`
+pub fn get_pid_path() -> Option<PathBuf> {
+    get_data_dir().map(|d| d.join("opencode-cloud.pid"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_config_dir_exists() {
+        let dir = get_config_dir();
+        assert!(dir.is_some());
+        let path = dir.unwrap();
+        assert!(path.ends_with("opencode-cloud"));
+    }
+
+    #[test]
+    fn test_data_dir_exists() {
+        let dir = get_data_dir();
+        assert!(dir.is_some());
+        let path = dir.unwrap();
+        assert!(path.ends_with("opencode-cloud"));
+    }
+
+    #[test]
+    fn test_config_path_ends_with_config_json() {
+        let path = get_config_path();
+        assert!(path.is_some());
+        assert!(path.unwrap().ends_with("config.json"));
+    }
+
+    #[test]
+    fn test_pid_path_ends_with_pid() {
+        let path = get_pid_path();
+        assert!(path.is_some());
+        assert!(path.unwrap().ends_with("opencode-cloud.pid"));
+    }
+}

package/src/config/schema.rs

@@ -0,0 +1,98 @@
+//! Configuration schema for opencode-cloud
+//!
+//! Defines the structure and defaults for the config.json file.
+
+use serde::{Deserialize, Serialize};
+
+/// Main configuration structure for opencode-cloud
+///
+/// Serialized to/from `~/.config/opencode-cloud/config.json`
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Config {
+    /// Config file version for migrations
+    pub version: u32,
+
+    /// Port for the opencode web UI (default: 8080)
+    #[serde(default = "default_port")]
+    pub port: u16,
+
+    /// Bind address (default: "localhost")
+    /// Use "localhost" for local-only access (secure default)
+    /// Use "0.0.0.0" for network access (requires explicit opt-in)
+    #[serde(default = "default_bind")]
+    pub bind: String,
+
+    /// Auto-restart service on crash (default: true)
+    #[serde(default = "default_auto_restart")]
+    pub auto_restart: bool,
+}
+
+fn default_port() -> u16 {
+    8080
+}
+
+fn default_bind() -> String {
+    "localhost".to_string()
+}
+
+fn default_auto_restart() -> bool {
+    true
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            version: 1,
+            port: default_port(),
+            bind: default_bind(),
+            auto_restart: default_auto_restart(),
+        }
+    }
+}
+
+impl Config {
+    /// Create a new Config with default values
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_config() {
+        let config = Config::default();
+        assert_eq!(config.version, 1);
+        assert_eq!(config.port, 8080);
+        assert_eq!(config.bind, "localhost");
+        assert!(config.auto_restart);
+    }
+
+    #[test]
+    fn test_serialize_deserialize_roundtrip() {
+        let config = Config::default();
+        let json = serde_json::to_string(&config).unwrap();
+        let parsed: Config = serde_json::from_str(&json).unwrap();
+        assert_eq!(config, parsed);
+    }
+
+    #[test]
+    fn test_deserialize_with_missing_optional_fields() {
+        let json = r#"{"version": 1}"#;
+        let config: Config = serde_json::from_str(json).unwrap();
+        assert_eq!(config.version, 1);
+        assert_eq!(config.port, 8080);
+        assert_eq!(config.bind, "localhost");
+        assert!(config.auto_restart);
+    }
+
+    #[test]
+    fn test_reject_unknown_fields() {
+        let json = r#"{"version": 1, "unknown_field": "value"}"#;
+        let result: Result<Config, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+}

package/src/lib.rs

@@ -0,0 +1,35 @@
+//! opencode-cloud-core - Core library for opencode-cloud
+//!
+//! This library provides the shared functionality for both the Rust CLI
+//! and Node.js bindings via NAPI-RS.
+
+pub mod config;
+pub mod singleton;
+pub mod version;
+
+// Re-export version functions for Rust consumers
+pub use version::{get_version, get_version_long};
+
+// Re-export config types and functions
+pub use config::{Config, load_config, save_config};
+
+// Re-export singleton types
+pub use singleton::{InstanceLock, SingletonError};
+
+// NAPI bindings for Node.js consumers (only when napi feature is enabled)
+#[cfg(feature = "napi")]
+use napi_derive::napi;
+
+/// Get the version string for Node.js consumers
+#[cfg(feature = "napi")]
+#[napi]
+pub fn get_version_js() -> String {
+    get_version()
+}
+
+/// Get the long version string with build info for Node.js consumers
+#[cfg(feature = "napi")]
+#[napi]
+pub fn get_version_long_js() -> String {
+    get_version_long()
+}

package/src/singleton/mod.rs

@@ -0,0 +1,249 @@
+//! Singleton enforcement via PID lock
+//!
+//! Ensures only one instance of opencode-cloud can run at a time.
+//! Uses a PID file with stale detection - if a previous process crashed
+//! without cleaning up, the stale lock is automatically removed.
+
+use std::fs::{self, File};
+use std::io::{Read, Write};
+use std::path::PathBuf;
+
+use thiserror::Error;
+
+/// Errors that can occur during singleton lock operations
+#[derive(Error, Debug)]
+pub enum SingletonError {
+    /// Another instance is already running
+    #[error("Another instance is already running (PID: {0})")]
+    AlreadyRunning(u32),
+
+    /// Failed to create the lock directory
+    #[error("Failed to create lock directory: {0}")]
+    CreateDirFailed(String),
+
+    /// Failed to create or manage the lock file
+    #[error("Failed to create lock file: {0}")]
+    LockFailed(String),
+
+    /// The lock file path could not be determined
+    #[error("Invalid lock file path")]
+    InvalidPath,
+}
+
+/// A guard that holds the singleton instance lock
+///
+/// The lock is automatically released when this struct is dropped.
+/// The PID file is removed on drop to allow other instances to start.
+pub struct InstanceLock {
+    pid_path: PathBuf,
+}
+
+impl InstanceLock {
+    /// Attempt to acquire the singleton lock
+    ///
+    /// # Returns
+    /// - `Ok(InstanceLock)` if the lock was successfully acquired
+    /// - `Err(SingletonError::AlreadyRunning(pid))` if another instance is running
+    /// - `Err(SingletonError::*)` for other errors
+    ///
+    /// # Stale Lock Detection
+    /// If a PID file exists but the process is no longer running,
+    /// the stale file is automatically cleaned up before acquiring the lock.
+    pub fn acquire(pid_path: PathBuf) -> Result<Self, SingletonError> {
+        // Ensure parent directory exists
+        if let Some(parent) = pid_path.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|e| SingletonError::CreateDirFailed(e.to_string()))?;
+        }
+
+        // Check if PID file exists
+        if pid_path.exists() {
+            // Read existing PID
+            let mut file =
+                File::open(&pid_path).map_err(|e| SingletonError::LockFailed(e.to_string()))?;
+            let mut contents = String::new();
+            file.read_to_string(&mut contents)
+                .map_err(|e| SingletonError::LockFailed(e.to_string()))?;
+
+            if let Ok(pid) = contents.trim().parse::<u32>() {
+                // Check if process is still running
+                if is_process_running(pid) {
+                    return Err(SingletonError::AlreadyRunning(pid));
+                }
+                // Stale PID file - process not running, remove it
+                tracing::info!("Removing stale PID file (PID {} not running)", pid);
+            }
+            // Remove stale/invalid PID file
+            fs::remove_file(&pid_path).map_err(|e| SingletonError::LockFailed(e.to_string()))?;
+        }
+
+        // Write our PID
+        let mut file =
+            File::create(&pid_path).map_err(|e| SingletonError::LockFailed(e.to_string()))?;
+        write!(file, "{}", std::process::id())
+            .map_err(|e| SingletonError::LockFailed(e.to_string()))?;
+
+        tracing::debug!("Acquired singleton lock at: {}", pid_path.display());
+
+        Ok(Self { pid_path })
+    }
+
+    /// Explicitly release the lock
+    ///
+    /// This is called automatically on drop, but can be called explicitly
+    /// if you want to release the lock early.
+    pub fn release(self) {
+        // Dropping self will call Drop::drop which removes the file
+    }
+
+    /// Get the path to the PID file
+    pub fn pid_path(&self) -> &PathBuf {
+        &self.pid_path
+    }
+}
+
+impl Drop for InstanceLock {
+    fn drop(&mut self) {
+        if let Err(e) = fs::remove_file(&self.pid_path) {
+            tracing::warn!("Failed to remove PID file on drop: {}", e);
+        } else {
+            tracing::debug!("Released singleton lock: {}", self.pid_path.display());
+        }
+    }
+}
+
+/// Check if a process with the given PID is currently running
+///
+/// Uses platform-specific methods to check process existence:
+/// - Unix: `kill(pid, 0)` - signal 0 checks existence without sending signal
+/// - Windows: OpenProcess API (deferred to v2)
+fn is_process_running(pid: u32) -> bool {
+    #[cfg(unix)]
+    {
+        // On Unix, sending signal 0 checks if process exists
+        // without actually sending a signal
+        match std::process::Command::new("kill")
+            .args(["-0", &pid.to_string()])
+            .output()
+        {
+            Ok(output) => output.status.success(),
+            Err(_) => {
+                // Fallback: check /proc on Linux
+                #[cfg(target_os = "linux")]
+                {
+                    std::path::Path::new(&format!("/proc/{}", pid)).exists()
+                }
+                #[cfg(not(target_os = "linux"))]
+                {
+                    // On macOS, if kill -0 fails, assume process doesn't exist
+                    false
+                }
+            }
+        }
+    }
+
+    #[cfg(windows)]
+    {
+        // Windows support deferred to v2
+        // For now, assume process is not running if we can't check
+        false
+    }
+
+    #[cfg(not(any(unix, windows)))]
+    {
+        // Unknown platform - assume not running
+        false
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_acquire_creates_pid_file() {
+        let temp_dir = TempDir::new().unwrap();
+        let pid_path = temp_dir.path().join("test.pid");
+
+        let lock = InstanceLock::acquire(pid_path.clone()).unwrap();
+
+        // Verify PID file exists
+        assert!(pid_path.exists());
+
+        // Verify it contains our PID
+        let contents = std::fs::read_to_string(&pid_path).unwrap();
+        let written_pid: u32 = contents.trim().parse().unwrap();
+        assert_eq!(written_pid, std::process::id());
+
+        // Drop the lock
+        drop(lock);
+
+        // Verify PID file was removed
+        assert!(!pid_path.exists());
+    }
+
+    #[test]
+    fn test_acquire_fails_when_already_locked() {
+        let temp_dir = TempDir::new().unwrap();
+        let pid_path = temp_dir.path().join("test.pid");
+
+        // Acquire first lock
+        let _lock1 = InstanceLock::acquire(pid_path.clone()).unwrap();
+
+        // Try to acquire second lock - should fail
+        let result = InstanceLock::acquire(pid_path.clone());
+        assert!(matches!(result, Err(SingletonError::AlreadyRunning(_))));
+    }
+
+    #[test]
+    fn test_stale_lock_cleanup() {
+        let temp_dir = TempDir::new().unwrap();
+        let pid_path = temp_dir.path().join("test.pid");
+
+        // Write a fake PID file with a PID that doesn't exist
+        // Using PID 999999 which is very unlikely to be running
+        std::fs::write(&pid_path, "999999").unwrap();
+
+        // Should be able to acquire lock (stale PID will be cleaned up)
+        let lock = InstanceLock::acquire(pid_path.clone());
+
+        // On Unix, this should succeed because 999999 likely isn't running
+        // On Windows or if 999999 happens to be running, this might fail
+        // which is acceptable - the test demonstrates the stale detection works
+        if lock.is_ok() {
+            assert!(pid_path.exists());
+            let contents = std::fs::read_to_string(&pid_path).unwrap();
+            let written_pid: u32 = contents.trim().parse().unwrap();
+            assert_eq!(written_pid, std::process::id());
+        }
+    }
+
+    #[test]
+    fn test_is_process_running_with_current_process() {
+        let current_pid = std::process::id();
+        assert!(is_process_running(current_pid));
+    }
+
+    #[test]
+    fn test_is_process_running_with_invalid_pid() {
+        // PID 0 is the kernel, PID 1 is init - use a very high unlikely PID
+        let unlikely_pid = 4_000_000_000;
+        assert!(!is_process_running(unlikely_pid));
+    }
+
+    #[test]
+    fn test_creates_parent_directories() {
+        let temp_dir = TempDir::new().unwrap();
+        let pid_path = temp_dir
+            .path()
+            .join("deep")
+            .join("nested")
+            .join("dir")
+            .join("test.pid");
+
+        let lock = InstanceLock::acquire(pid_path.clone()).unwrap();
+        assert!(pid_path.exists());
+        drop(lock);
+    }
+}

package/src/version.rs

@@ -0,0 +1,50 @@
+//! Version information for opencode-cloud
+
+/// Get the current version string
+pub fn get_version() -> String {
+    env!("CARGO_PKG_VERSION").to_string()
+}
+
+/// Get the long version string with build information
+///
+/// Returns version plus build metadata when available (git commit, build date).
+/// Falls back gracefully if build info is not available.
+pub fn get_version_long() -> String {
+    let version = get_version();
+
+    // Build info is set via environment variables during build
+    // These may be set by CI or build scripts
+    let git_hash = option_env!("OCC_GIT_HASH").unwrap_or("unknown");
+    let build_date = option_env!("OCC_BUILD_DATE").unwrap_or("unknown");
+
+    format!(
+        "{version} (git: {git_hash}, built: {build_date})",
+        version = version,
+        git_hash = git_hash,
+        build_date = build_date
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_version_returns_valid_semver() {
+        let version = get_version();
+        assert!(!version.is_empty());
+        // Basic semver format check
+        let parts: Vec<&str> = version.split('.').collect();
+        assert!(parts.len() >= 2, "Version should have at least major.minor");
+    }
+
+    #[test]
+    fn test_get_version_long_contains_version() {
+        let long = get_version_long();
+        let short = get_version();
+        assert!(
+            long.contains(&short),
+            "Long version should contain short version"
+        );
+    }
+}