nim-sync 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/README.md

@@ -0,0 +1,199 @@
+# OpenCode NVIDIA NIM Sync Plugin
+
+A global OpenCode plugin that automatically synchronizes NVIDIA NIM models with your OpenCode configuration on startup.
+
+## Features
+
+- **Automatic Sync**: On OpenCode startup, fetches the latest NVIDIA model catalog
+- **Config Management**: Updates `provider.nim.models` in your OpenCode config
+- **TTL Cache**: Only refreshes models if last refresh was >24 hours ago
+- **Manual Refresh**: `/nim-refresh` command for force updates
+- **Atomic Operations**: Safe file writes with backups and locking
+- **Error Handling**: Graceful fallback when offline or missing API key
+
+## Installation
+
+Install the published plugin from npm through your OpenCode config.
+npm plugins are installed automatically using Bun at startup, so end users do not need to run `npm install`, build the plugin locally, or copy files into the plugins directory.
+If you are working from this repository before the package is published, use the local testing flow farther below instead.
+
+Add `nim-sync` to the `plugin` array in your global or project OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["nim-sync"]
+}
+```
+
+After adding the plugin, restart OpenCode.
+Ensure you have an NVIDIA API key either:
+   - Set `NVIDIA_API_KEY` environment variable
+   - Run `/connect` in OpenCode to add NVIDIA credentials
+
+On startup, the plugin refreshes the NVIDIA model catalog in the background and registers `/nim-refresh` for manual updates.
+
+## Configuration
+
+The plugin manages this subtree in your OpenCode config:
+
+```json
+{
+  "provider": {
+    "nim": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "NVIDIA NIM",
+      "options": {
+        "baseURL": "https://integrate.api.nvidia.com/v1"
+      },
+      "models": {
+        "meta/llama-3.1-70b-instruct": {
+          "name": "Meta Llama 3.1 70B Instruct"
+        }
+      }
+    }
+  }
+}
+```
+
+## User Ownership
+
+The plugin ONLY manages:
+- `provider.nim.npm`
+- `provider.nim.name`
+- `provider.nim.options.baseURL`
+- `provider.nim.models`
+
+You retain control over:
+- Top-level `model` selection
+- `small_model` setting
+- Per-model option overrides
+- Any unrelated providers
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test -- --run
+
+# Run tests with coverage
+npm run test:coverage -- --run
+
+# Build the bundled plugin artifact
+npm run build
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+### Local Testing
+
+If you are testing the plugin before it is published to npm, you can still use the bundled artifact in `dist/nim-sync.mjs` with OpenCode's local plugin directory.
+
+## Release Automation
+
+This repository includes [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which publishes to npm whenever you push a `v*` tag.
+The workflow verifies that the tag matches `package.json`, then runs `npm ci`, tests, lint, typecheck, build, and `npm publish`.
+
+### One-Time Setup
+
+Because `nim-sync` is not published yet, the first release must be done manually once so the package exists on npm.
+
+1. Log into npm on your release machine:
+
+```bash
+npm adduser
+```
+
+2. Publish the first version from this repository root:
+
+```bash
+npm publish
+```
+
+3. Open the npm package settings for `nim-sync` and add a `Trusted Publisher` for GitHub Actions:
+   - Owner/user: `EthanBerlant`
+   - Repository: `nim-sync`
+   - Workflow filename: `publish.yml`
+
+After that one-time setup, future releases can be fully automated from Git tags.
+
+If you cloned the repository before the rename, update your local remote:
+
+```bash
+git remote set-url origin https://github.com/EthanBerlant/nim-sync.git
+```
+
+### Releasing a New Version
+
+The easiest flow is:
+
+```bash
+npm version patch
+git push origin HEAD --follow-tags
+```
+
+Use `npm version minor` or `npm version major` when appropriate.
+
+If you prefer to create the tag manually instead of using `npm version`, this works too:
+
+```bash
+npm version --no-git-tag-version 1.0.1
+git add package.json package-lock.json
+git commit -m "Release 1.0.1"
+git tag v1.0.1
+git push origin HEAD
+git push origin v1.0.1
+```
+
+### What the Workflow Does
+
+On every pushed `v*` tag, GitHub Actions:
+- Verifies the pushed tag matches `package.json`
+- Installs dependencies with `npm ci`
+- Runs the test suite
+- Runs lint and typecheck
+- Builds the package
+- Publishes the package to npm using GitHub OIDC trusted publishing
+
+## Test-Driven Development
+
+This project follows strict TDD principles:
+
+1. **Tests First**: All functionality has failing tests written first
+2. **80%+ Coverage**: Unit, integration, and user journey tests
+3. **User Journeys**: Tests based on actual user scenarios
+4. **Red-Green-Refactor**: Standard TDD workflow
+
+## Architecture
+
+### File Structure
+```
+src/
+├── index.ts                 # Plugin entry point
+├── plugin/nim-sync.ts       # Main plugin implementation
+├── lib/file-utils.ts        # File operations with JSONC support
+├── types/index.ts          # TypeScript definitions
+└── __tests__/              # Test suites
+
+scripts/
+├── clean.mjs                # Cross-platform dist cleanup
+└── bundle.mjs               # Standalone plugin bundling
+```
+
+### Key Components
+- **Plugin Initialization**: Runs async refresh on OpenCode startup
+- **Credential Resolution**: Checks `/connect` auth or env var
+- **NVIDIA API Client**: Fetches `/v1/models` endpoint
+- **Config Management**: Atomically updates OpenCode config
+- **Cache System**: 24-hour TTL to avoid excessive API calls
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from './types/index.js';
+declare const _default: Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;wBAGd,MAAM;AAAtC,wBAAsC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { syncNIMModels } from './plugin/nim-sync.js';
+export default syncNIMModels;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,eAAe,aAAuB,CAAA"}

package/dist/lib/file-utils.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Options for atomic file write operations.
+ */
+export interface AtomicWriteOptions {
+    /** Whether to create a backup before overwriting */
+    backup?: boolean;
+    /** Whether to create backup directory if it doesn't exist */
+    createBackupDir?: boolean;
+}
+/**
+ * Timeout for NVIDIA API requests in milliseconds.
+ */
+export declare const API_TIMEOUT_MS = 30000;
+/**
+ * Time-to-live for cached model data in milliseconds (24 hours).
+ */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Threshold for considering a lock stale in milliseconds (5 minutes).
+ */
+export declare const LOCK_STALE_THRESHOLD_MS: number;
+/**
+ * Interval between lock acquisition retry attempts in milliseconds.
+ */
+export declare const LOCK_RETRY_INTERVAL_MS = 100;
+/**
+ * Minimum interval between manual refresh operations in milliseconds (60 seconds).
+ */
+export declare const MIN_MANUAL_REFRESH_INTERVAL_MS = 60000;
+/**
+ * Maximum number of backup files to retain.
+ */
+export declare const MAX_BACKUPS = 5;
+/**
+ * Reads and parses a JSONC (JSON with Comments) file.
+ *
+ * @param filePath - Path to the JSONC file
+ * @param validate - Optional validation function to ensure type safety
+ * @returns Parsed content of type T, or empty object if file doesn't exist
+ * @throws Error if file read fails (except ENOENT) or if validation fails
+ */
+export declare function readJSONC<T = unknown>(filePath: string, validate?: (data: unknown) => data is T): Promise<T>;
+/**
+ * Writes data to a JSONC file with atomic operations.
+ *
+ * @param filePath - Path to write the file
+ * @param data - Data to serialize as JSON
+ * @param options - Optional backup and directory creation settings
+ */
+export declare function writeJSONC<T = unknown>(filePath: string, data: T, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Updates a specific path within a JSONC file while preserving unrelated
+ * comments and formatting.
+ *
+ * @param filePath - Path to the JSONC file
+ * @param jsonPath - JSON path to update
+ * @param data - Value to write at the given path
+ * @param options - Optional backup and directory creation settings
+ */
+export declare function updateJSONCPath<T = unknown>(filePath: string, jsonPath: Array<string | number>, data: T, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Atomically writes content to a file using temp file + rename pattern.
+ * Optionally creates backups before overwriting and cleans up old backups.
+ *
+ * @param filePath - Path to write the file
+ * @param content - String content to write
+ * @param options - Optional backup and directory creation settings
+ */
+export declare function atomicWrite(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Ensures a directory exists, creating it recursively if needed.
+ *
+ * @param dirPath - Path to the directory
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Returns the platform-specific config directory path.
+ *
+ * @returns Config directory path
+ */
+export declare function getConfigDir(): string;
+/**
+ * Returns the platform-specific cache directory path.
+ *
+ * @returns Cache directory path
+ */
+export declare function getCacheDir(): string;
+/**
+ * Returns the platform-specific data directory path.
+ *
+ * @returns Data directory path
+ */
+export declare function getDataDir(): string;
+/**
+ * Acquires an exclusive lock for coordinating file operations.
+ * Automatically cleans up stale locks from crashed processes.
+ *
+ * @param lockName - Name of the lock
+ * @param timeoutMs - Maximum time to wait for lock acquisition (default: 5000ms)
+ * @returns Function to release the lock
+ * @throws Error if lock cannot be acquired within timeout
+ */
+export declare function acquireLock(lockName: string, timeoutMs?: number): Promise<() => Promise<void>>;
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/lib/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/lib/file-utils.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,QAAS,CAAA;AAEpC;;GAEG;AACH,eAAO,MAAM,YAAY,QAAsB,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAgB,CAAA;AAEpD;;GAEG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC;;GAEG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAA;AAEpD;;GAEG;AACH,eAAO,MAAM,WAAW,IAAI,CAAA;AAE5B;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAChC,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAsCf;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9D;AA+BD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AA8CD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAuDlG"}

package/dist/lib/file-utils.js

@@ -0,0 +1,312 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { applyEdits, modify as modifyJSONC, parse as parseJSONC } from 'jsonc-parser/lib/esm/main.js';
+/**
+ * Timeout for NVIDIA API requests in milliseconds.
+ */
+export const API_TIMEOUT_MS = 30_000;
+/**
+ * Time-to-live for cached model data in milliseconds (24 hours).
+ */
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Threshold for considering a lock stale in milliseconds (5 minutes).
+ */
+export const LOCK_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+/**
+ * Interval between lock acquisition retry attempts in milliseconds.
+ */
+export const LOCK_RETRY_INTERVAL_MS = 100;
+/**
+ * Minimum interval between manual refresh operations in milliseconds (60 seconds).
+ */
+export const MIN_MANUAL_REFRESH_INTERVAL_MS = 60_000;
+/**
+ * Maximum number of backup files to retain.
+ */
+export const MAX_BACKUPS = 5;
+/**
+ * Reads and parses a JSONC (JSON with Comments) file.
+ *
+ * @param filePath - Path to the JSONC file
+ * @param validate - Optional validation function to ensure type safety
+ * @returns Parsed content of type T, or empty object if file doesn't exist
+ * @throws Error if file read fails (except ENOENT) or if validation fails
+ */
+export async function readJSONC(filePath, validate) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const errors = [];
+        const result = parseJSONC(content, errors);
+        if (errors.length > 0) {
+            const errorDetails = errors
+                .map(e => `Parse error code ${e.error} at offset ${e.offset}`)
+                .join('; ');
+            throw new Error(`JSONC parse errors in ${filePath}: ${errorDetails}`);
+        }
+        if (validate && !validate(result)) {
+            throw new Error(`Invalid data structure in ${filePath}`);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+}
+/**
+ * Writes data to a JSONC file with atomic operations.
+ *
+ * @param filePath - Path to write the file
+ * @param data - Data to serialize as JSON
+ * @param options - Optional backup and directory creation settings
+ */
+export async function writeJSONC(filePath, data, options) {
+    const content = JSON.stringify(data, null, 2);
+    await atomicWrite(filePath, content, options);
+}
+/**
+ * Updates a specific path within a JSONC file while preserving unrelated
+ * comments and formatting.
+ *
+ * @param filePath - Path to the JSONC file
+ * @param jsonPath - JSON path to update
+ * @param data - Value to write at the given path
+ * @param options - Optional backup and directory creation settings
+ */
+export async function updateJSONCPath(filePath, jsonPath, data, options) {
+    let existingContent = '';
+    try {
+        existingContent = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const eol = existingContent.includes('\r\n') ? '\r\n' : '\n';
+    const edits = modifyJSONC(existingContent, jsonPath, data, {
+        formattingOptions: {
+            insertSpaces: true,
+            tabSize: 2,
+            eol
+        }
+    });
+    const updatedContent = applyEdits(existingContent, edits);
+    await atomicWrite(filePath, updatedContent, options);
+}
+/**
+ * Atomically writes content to a file using temp file + rename pattern.
+ * Optionally creates backups before overwriting and cleans up old backups.
+ *
+ * @param filePath - Path to write the file
+ * @param content - String content to write
+ * @param options - Optional backup and directory creation settings
+ */
+export async function atomicWrite(filePath, content, options = {}) {
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.${Date.now()}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        if (options.backup) {
+            try {
+                await fs.access(filePath);
+                const backupDir = path.join(dir, 'backups');
+                if (options.createBackupDir) {
+                    await fs.mkdir(backupDir, { recursive: true });
+                }
+                const backupPath = path.join(backupDir, `${path.basename(filePath)}.${Date.now()}.bak`);
+                await fs.copyFile(filePath, backupPath);
+                // Clean up old backups after creating new one
+                await cleanupOldBackups(backupDir, path.basename(filePath));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw new Error(`Failed to create backup: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                }
+            }
+        }
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            await fs.unlink(tempPath);
+        }
+        catch {
+            // Ignore temp file cleanup failures
+        }
+        throw error;
+    }
+}
+/**
+ * Ensures a directory exists, creating it recursively if needed.
+ *
+ * @param dirPath - Path to the directory
+ */
+export async function ensureDir(dirPath) {
+    try {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            throw error;
+        }
+    }
+}
+/**
+ * Returns platform-specific paths for config, data, and cache directories.
+ * Handles Windows, Linux, and macOS path conventions.
+ *
+ * @returns Platform-specific directory paths
+ * @example
+ * ```typescript
+ * const paths = getPlatformPaths()
+ * // Windows: { config: 'C:\\Users\\username\\AppData\\Roaming\\opencode', ... }
+ * // Linux: { config: '/home/username/.config/opencode', ... }
+ * ```
+ */
+function getPlatformPaths() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const isWindows = process.platform === 'win32';
+    return {
+        config: isWindows
+            ? path.join(home, 'AppData', 'Roaming', 'opencode')
+            : path.join(home, '.config', 'opencode'),
+        data: isWindows
+            ? path.join(home, 'AppData', 'Roaming', 'opencode')
+            : path.join(home, '.local', 'share', 'opencode'),
+        cache: isWindows
+            ? path.join(home, 'AppData', 'Local', 'opencode', 'cache')
+            : path.join(home, '.cache', 'opencode')
+    };
+}
+/**
+ * Returns the platform-specific config directory path.
+ *
+ * @returns Config directory path
+ */
+export function getConfigDir() {
+    return getPlatformPaths().config;
+}
+/**
+ * Returns the platform-specific cache directory path.
+ *
+ * @returns Cache directory path
+ */
+export function getCacheDir() {
+    return getPlatformPaths().cache;
+}
+/**
+ * Returns the platform-specific data directory path.
+ *
+ * @returns Data directory path
+ */
+export function getDataDir() {
+    return getPlatformPaths().data;
+}
+/**
+ * Checks if a process with the given PID is currently running.
+ * Uses a non-destructive signal (0) to check process existence.
+ *
+ * @param pid - Process ID to check
+ * @returns true if the process exists, false otherwise
+ */
+function isProcessRunning(pid) {
+    try {
+        // Signal 0 doesn't kill the process, just checks if it exists
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cleans up old backup files, keeping only the most recent MAX_BACKUPS.
+ *
+ * @param backupDir - Directory containing backup files
+ * @param baseName - Base name of the file being backed up
+ */
+async function cleanupOldBackups(backupDir, baseName) {
+    try {
+        const files = await fs.readdir(backupDir);
+        const backups = files
+            .filter(f => f.startsWith(baseName) && f.endsWith('.bak'))
+            .map(f => ({
+            name: f,
+            // Extract timestamp from filename like "file.json.1234567890.bak"
+            timestamp: parseInt(f.split('.').slice(-2, -1)[0]) || 0
+        }))
+            .sort((a, b) => b.timestamp - a.timestamp); // Sort newest first
+        // Keep only the most recent backups
+        for (const oldBackup of backups.slice(MAX_BACKUPS)) {
+            await fs.unlink(path.join(backupDir, oldBackup.name));
+        }
+    }
+    catch {
+        // Ignore cleanup failures - don't want to fail the main operation
+    }
+}
+/**
+ * Acquires an exclusive lock for coordinating file operations.
+ * Automatically cleans up stale locks from crashed processes.
+ *
+ * @param lockName - Name of the lock
+ * @param timeoutMs - Maximum time to wait for lock acquisition (default: 5000ms)
+ * @returns Function to release the lock
+ * @throws Error if lock cannot be acquired within timeout
+ */
+export async function acquireLock(lockName, timeoutMs = 5000) {
+    const lockDir = getCacheDir();
+    const lockPath = path.join(lockDir, `${lockName}.lock`);
+    await ensureDir(lockDir);
+    try {
+        const lockContent = await fs.readFile(lockPath, 'utf-8');
+        const metadata = JSON.parse(lockContent);
+        const staleThreshold = Date.now() - LOCK_STALE_THRESHOLD_MS;
+        // Check if timestamp is stale OR if the holding process is no longer running
+        const isStale = metadata.timestamp < staleThreshold;
+        const processExists = metadata.pid ? isProcessRunning(metadata.pid) : true;
+        // Note: TOCTOU race possible between check and delete, but mitigated by
+        // atomic 'wx' flag in subsequent fs.open() call which provides ultimate protection
+        if (isStale || !processExists) {
+            await fs.unlink(lockPath);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            console.error('Failed to clean up stale lock');
+        }
+    }
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            const fd = await fs.open(lockPath, 'wx');
+            const metadata = {
+                pid: process.pid,
+                timestamp: Date.now()
+            };
+            await fd.writeFile(JSON.stringify(metadata));
+            await fd.close();
+            return async () => {
+                try {
+                    await fs.unlink(lockPath);
+                }
+                catch {
+                    // Ignore unlock failures
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+            await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
+        }
+    }
+    throw new Error(`Failed to acquire lock "${lockName}" after ${timeoutMs}ms`);
+}
+//# sourceMappingURL=file-utils.js.map

package/dist/lib/file-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.js","sourceRoot":"","sources":["../../src/lib/file-utils.ts"],"names":[],"mappings":"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"}