Skip to main content

dsh-atomic-write/packages/util/atomic-writeOfficial

175.3kStars19.0kForks0Issues752Watchers

Zero-dependency atomic file replacement: exclusive-create random-suffix temp + rename carrying the caller-stated permissions (writeFileAtomic)

Evidence3/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the deepseek-ai/deepseek-harness monorepo — stars and activity count the whole repository.

Language
TypeScript
License
MIT
Branch
master
ai-agentscordisdshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add npm:@deepseek-ai/dsh-atomic-write

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin deepseek-ai/deepseek-harness/packages/util/atomic-write for me: review the repository at https://github.com/deepseek-ai/deepseek-harness first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

English | 中文

Zero-dependency atomic file replacement shared by file-backed stores that must never leave partial, symlink-hijacked, or wider-than-intended content on disk — the user-settings document (dsh-settings-file) and the credentials store (dsh-credentials-local).

Surface

import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'

declare const text: string
declare const render: (previous: string) => string

await writeFileAtomic('/home/u/.dsh/settings.yaml', text, { mode: 0o600 })

// Read-modify-write against the same file from several processes.
await withFileLock('/home/u/.dsh/settings.yaml', async () => {
  await writeFileAtomic('/home/u/.dsh/settings.yaml', render(text), { mode: 0o600 })
})

writeFileAtomic commits one already-rendered string. The contract, in the order failures would exploit it:

  • Exclusive-create temp (wx, random suffix): the open refuses to follow a symlink planted at a guessable temp path.
  • The fresh inode carries mode through the rename: replacing a wider-permission file narrows it without a chmod race. mode is required so the permission decision stays visible at every call site (subject to the process umask, like every fresh inode).
  • rename replaces a symlinked target itself, never writing through to its referent.
  • Same-directory sibling keeps the rename on one filesystem, so the swap stays atomic.
  • Parent directories are created; on any failure the temp is removed and the failure rethrown; readers observe either the old or the new complete content.

withFileLock serializes the writers of one file across processes, for the read-render-commit cycles a bare atomic commit cannot make safe on its own. The lock is a wx-created <filename>.lock sibling, so readers never contend; waiters back off exponentially and fail with a timeout rather than block forever. EEXIST identifies contention directly; EPERM does so only when a fresh lstat confirms that the lock path exists, covering Windows exclusive-create behavior without hiding an unrelated permission failure. A contender never removes the existing lock: age cannot distinguish a crashed owner from a paused live writer.

Model Experience

None, as this is a pure filesystem primitive; nothing here reaches a model request.

KV Cache effect

None; nothing here enters a request prefix.

Known Limitations and Deferred Work

  • Atomic, not durable — no fsync of the file or its directory, so after a crash the rename may be observed unwound. The file-backed stores here re-read and republish on boot, keeping durability the caller's policy.
  • String content only — no Buffer or stream form until a consumer needs one.
  • Orphaned locks require operator recovery — a process that exits while holding the lock can leave the sibling behind. Later writers time out without deleting it; an operator removes it only after verifying that no writer still owns it. File age alone is not safe evidence of abandonment.

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/deepseek-ai/deepseek-harness/packages/util/atomic-write)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory