memcue-dsh 0.4.0 → 0.5.1

package/README.md

@@ -42,9 +42,12 @@ once; `memcue_correct` of an approved fact is a deliberate correction, not a can
 
 ## Supported dsh
 
-The memcue binary must be 0.4.0 or newer: the plugin asks `memcue version -json` when it loads and, on an older
-binary, turns the session card and extraction off with one warning (recall keeps working, because the 0.3 hook is
-compatible). A build from source reports a suffixed version and counts as the current tree.
+The plugin asks `memcue version -json` when it loads. Without a configured `binary` or `MEMCUE_BIN`, a missing binary
+or one older than the plugin's release is replaced by that release, installed into
+`$XDG_DATA_HOME/memcue/<version>/` (`MEMCUE_AUTO_INSTALL=0` turns that off): an older release may not open the base
+the new one writes. A binary older than 0.4.0 that stays, a configured one or a failed install, turns the session card
+and extraction off with one warning (recall keeps working). A build from source reports a suffixed version and counts
+as the current tree.
 
 Tested with `dsh 0.2.0-rc.2`. Both the repository bundle and the standalone package declare
 `>=0.2.0-rc.2 <0.3.0` peer ranges for `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-tools`, so dsh's compatibility
@@ -57,7 +60,10 @@ directory's `cordis.patch.yml`. The plugin directory is also its own package, fo
 development. The entry is plain ESM (`src/index.mjs`) on purpose: dsh installs a bundle under `node_modules`, where
 Node refuses to strip TypeScript types, so a `.ts` entry cannot be loaded from an installed package.
 
-1. Put the `memcue` binary where the dsh process can run it and note its absolute path.
+1. Optional: put the `memcue` binary where the dsh process can run it and note its absolute path. Without a
+   configured `binary` and without a current `memcue` on `PATH`, the plugin installs the binary of its own release
+   into `${XDG_DATA_HOME:-~/.local/share}/memcue/<version>/`, the directory the Claude Code plugin uses
+   (`MEMCUE_AUTO_INSTALL=0` turns that off; see [Binary from the plugin](../../README.md#binary-from-the-plugin)).
 
 2. Install the bundle from the repository:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memcue-dsh",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "memcue long-term memory for DeepSeek Harness (dsh): facts recalled before a step, extracted when a turn ends",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -18,12 +18,13 @@
  * @module memcue-dsh
  */
 import { spawn } from 'node:child_process'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
 import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { install, pluginVersion } from './install.mjs'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'memcue'
@@ -135,6 +136,8 @@ function settingsOf(config) {
 	}
 	return {
 		binary: expandHome(textOf(raw.binary, 'binary', process.env.MEMCUE_BIN || DEFAULTS.binary)) || DEFAULTS.binary,
+		// A configured binary is used as it is; the default one may be replaced by the release this plugin installs.
+		pinned: Boolean(textOf(raw.binary, 'binary', process.env.MEMCUE_BIN || '')),
 		facts,
 		factsKey: resolve(facts || defaultFacts()),
 		// The global off switch wins over the profile: it is the one setting a user adds to a container or a launcher
@@ -406,10 +409,11 @@ async function readState(path) {
 }
 
 /** Write the checkpoint atomically: a crash leaves the old file or the new one, never a half-written one.
- * The batch holds raw messages, so the directory and file are private to the user. */
+ * The batch holds raw messages, so the directory and file are private to the user. Each write has its own temporary
+ * file: two plugin instances on one session would otherwise rename each other's file and fail with ENOENT (#261). */
 async function writeState(path, state) {
 	await mkdir(dirname(path), { recursive: true, mode: 0o700 })
-	const tmp = `${path}.tmp`
+	const tmp = `${path}.${randomUUID()}.tmp`
 	await writeFile(tmp, JSON.stringify(state), { mode: 0o600 })
 	await rename(tmp, path)
 }
@@ -512,21 +516,39 @@ export function apply(ctx, config) {
 		interpolate: false,
 	})
 
-	// The binary is installed separately from this package: check once that it has the commands the plugin uses, and
-	// turn the card and extraction off with one clear line instead of failing them every turn.
-	const checkBinary = async () => {
+	// The version the binary reports, and whether there is a binary at all.
+	const versionOf = async () => {
 		// `-json` is 0.4.0 too: an older binary answers the flag with an error, so ask for the plain form as well.
 		let { code, out } = await runMemcue(settings, ['version', '-json'], { timeoutMs: 5_000 })
 		if (code !== 0) ({ code, out } = await runMemcue(settings, ['version'], { timeoutMs: 5_000 }))
-		let reported = ''
-		if (code === 0) {
+		if (code !== 0) return { found: false, reported: '' }
+		try {
+			return { found: true, reported: String(JSON.parse(out)?.version ?? '') }
+		} catch {
+			return { found: true, reported: out.trim().split(/\s+/)[0] ?? '' }
+		}
+	}
+
+	// Check once that the binary has the commands the plugin uses. Without a configured binary, a missing one, or one
+	// older than this plugin's release, is replaced by that release, installed or downloaded: an older release may not
+	// open the base the plugin's release writes (#272). Until that is done recall uses what PATH has. Anything else
+	// turns the card and extraction off with one clear line instead of failing every turn.
+	const checkBinary = async () => {
+		let { found, reported } = await versionOf()
+		let version = ''
+		try {
+			version = await pluginVersion()
+		} catch {}
+		if (!settings.pinned && !(found && versionAtLeast(reported, version || MIN_BINARY))) {
 			try {
-				reported = String(JSON.parse(out)?.version ?? '')
-			} catch {
-				reported = out.trim().split(/\s+/)[0] ?? ''
+				version = version || (await pluginVersion())
+				settings.binary = await install(version)
+				;({ found, reported } = await versionOf())
+			} catch (error) {
+				if (!found) console.warn(`memcue: no memcue binary on PATH, and the plugin could not install ${version || 'its release'}: ${error.message}`)
 			}
 		}
-		if (versionAtLeast(reported, MIN_BINARY)) return
+		if (!found || versionAtLeast(reported, MIN_BINARY)) return
 		compatible = false
 		extraction = false
 		console.warn(`memcue: binary ${reported || 'unknown'} is older than ${MIN_BINARY}; the session card and extraction are off, recall still works. Update memcue.`)

package/src/install.mjs

@@ -0,0 +1,120 @@
+/**
+ * Installs the memcue binary of this plugin's release when none is configured, the way the Claude Code plugin does:
+ * into `${XDG_DATA_HOME:-~/.local/share}/memcue/<version>/memcue`, a directory the two plugins share, checked
+ * against the release's `checksums.txt`. `MEMCUE_AUTO_INSTALL=0` turns it off.
+ *
+ * @module memcue-dsh/install
+ */
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { access, constants, chmod, mkdir, mkdtemp, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Where the releases are downloaded from; MEMCUE_RELEASE_URL replaces it, for a mirror or a test. */
+const RELEASES = 'https://github.com/juev/memcue/releases/download'
+
+/** A lock left by a crashed install stops blocking after this long. */
+const STALE_LOCK_MS = 10 * 60_000
+
+/**
+ * The version of this plugin, which is the release of the binary it installs.
+ * @returns the version from package.json.
+ */
+export async function pluginVersion() {
+	const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'))
+	return String(manifest.version)
+}
+
+/**
+ * Path of the installed binary of a release.
+ * @param version - release version without the leading v.
+ * @returns the absolute path, whether or not it exists.
+ */
+export function installedPath(version) {
+	const data = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share')
+	return join(data, 'memcue', version, 'memcue')
+}
+
+/**
+ * Whether path is an executable file.
+ * @param path - file to check.
+ * @returns true when it can be run.
+ */
+export async function executable(path) {
+	try {
+		await access(path, constants.X_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
+function target() {
+	const os = { darwin: 'darwin', linux: 'linux' }[process.platform]
+	const arch = { x64: 'amd64', arm64: 'arm64' }[process.arch]
+	if (!os || !arch) throw new Error(`no memcue release for ${process.platform}/${process.arch}`)
+	return `${os}_${arch}`
+}
+
+async function download(url, timeoutMs) {
+	const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+	if (!response.ok) throw new Error(`${url}: ${response.status} ${response.statusText}`)
+	return Buffer.from(await response.arrayBuffer())
+}
+
+function untar(archive, dir) {
+	return new Promise((resolve, reject) => {
+		const child = spawn('tar', ['-xzf', archive, '-C', dir, 'memcue'], { stdio: ['ignore', 'ignore', 'pipe'] })
+		let err = ''
+		child.stderr.on('data', (chunk) => { err += chunk })
+		child.on('error', reject)
+		child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`tar: ${err.trim()}`))))
+	})
+}
+
+/**
+ * Install the binary of a release unless it is there already. The archive must match its line in the release's
+ * checksums.txt; it is unpacked next to the target and moved into place, so a reader never sees half a binary. A lock
+ * directory, the same one the Claude Code plugin takes, keeps two installs from racing.
+ * @param version - release version without the leading v.
+ * @returns the path of the installed binary.
+ * @throws when auto-install is off, the platform has no release, or the download or the checksum fails.
+ */
+export async function install(version) {
+	const path = installedPath(version)
+	if (await executable(path)) return path
+	if (process.env.MEMCUE_AUTO_INSTALL === '0') throw new Error('MEMCUE_AUTO_INSTALL=0')
+	const archive = `memcue_${version}_${target()}.tar.gz`
+	const dir = join(path, '..')
+	await mkdir(dir, { recursive: true })
+	const lock = join(dir, '.lock')
+	try {
+		if (Date.now() - (await stat(lock)).mtimeMs > STALE_LOCK_MS) await rmdir(lock)
+	} catch {
+		// no lock
+	}
+	try {
+		await mkdir(lock)
+	} catch {
+		throw new Error('another install of memcue is running')
+	}
+	const tmp = await mkdtemp(join(dir, '.tmp.'))
+	try {
+		const base = `${process.env.MEMCUE_RELEASE_URL || RELEASES}/v${version}`
+		const [data, sums] = await Promise.all([download(`${base}/${archive}`, 45_000),
+			download(`${base}/checksums.txt`, 15_000)])
+		const want = sums.toString('utf8').split('\n').map((line) => line.trim().split(/\s+/))
+			.find(([, file]) => file === archive)?.[0]
+		const got = createHash('sha256').update(data).digest('hex')
+		if (!want || want !== got) throw new Error(`checksum of ${archive} does not match checksums.txt`)
+		await writeFile(join(tmp, archive), data)
+		await untar(join(tmp, archive), tmp)
+		await chmod(join(tmp, 'memcue'), 0o755)
+		await rename(join(tmp, 'memcue'), path)
+		return path
+	} finally {
+		await rm(tmp, { recursive: true, force: true })
+		await rmdir(lock).catch(() => {})
+	}
+}