@emptyos/client 0.1.0

package/lib/platform-update.js

@@ -0,0 +1,304 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseReleaseArtifactBytes } from '../../provision/lib/platform-release-artifact.mjs';
+import { PLATFORM_RELEASE_CATALOG_URL } from '../../provision/lib/platform-release-channel.mjs';
+import { ClientError } from './errors.js';
+import { runCaptured, runInherited } from './process.js';
+import { sshCommand, sshTransport } from './rpc.js';
+
+const CATALOG_COMPONENT = 'emptyos-platform-catalog';
+const CATALOG_VERSION = 1;
+const UPDATE_PROTOCOL_VERSION = 1;
+const SHA256 = /^[0-9a-f]{64}$/;
+const MAX_CATALOG_BYTES = 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function validateHttpsUrl(value, label) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ClientError(`The ${label} must be an HTTPS URL`);
+  }
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash) {
+    throw new ClientError(`The ${label} must be an HTTPS URL without credentials or a fragment`);
+  }
+  return url.href;
+}
+
+export function validateCatalogUrl(value) {
+  return validateHttpsUrl(value, 'platform release catalog');
+}
+
+export function parseReleaseCatalog(value, catalogUrl) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      value.version !== CATALOG_VERSION || value.component !== CATALOG_COMPONENT ||
+      value.updateProtocol !== UPDATE_PROTOCOL_VERSION) {
+    throw new ClientError(`Invalid EmptyOS platform release catalog at ${catalogUrl}`);
+  }
+  if (!value.release || typeof value.release !== 'object' || Array.isArray(value.release)) {
+    throw new ClientError(`Platform release catalog at ${catalogUrl} has no release`);
+  }
+  let artifactUrl;
+  try {
+    artifactUrl = new URL(value.release.url, catalogUrl);
+  } catch {
+    throw new ClientError(`Platform release catalog at ${catalogUrl} has an invalid artifact URL`);
+  }
+  const resolvedArtifactUrl = validateHttpsUrl(
+    artifactUrl.href,
+    `platform release catalog at ${catalogUrl} artifact`,
+  );
+  const artifactSha256 = String(value.release.sha256 ?? '');
+  if (!SHA256.test(artifactSha256)) {
+    throw new ClientError(`Platform release catalog at ${catalogUrl} has an invalid artifact digest`);
+  }
+  return { catalogUrl, artifactUrl: resolvedArtifactUrl, artifactSha256 };
+}
+
+async function fetchHttps(start, { timeout, label }, fetchImpl) {
+  let current = validateHttpsUrl(start, label);
+  for (let redirects = 0; redirects <= 5; redirects += 1) {
+    let response;
+    try {
+      response = await fetchImpl(current, { redirect: 'manual', signal: AbortSignal.timeout(timeout) });
+    } catch (error) {
+      throw new ClientError(`Cannot fetch ${label} at ${current}: ${error.message}`);
+    }
+    if (!REDIRECT_STATUSES.has(response.status)) {
+      const finalUrl = response.url ? validateHttpsUrl(response.url, label) : current;
+      return { response, finalUrl };
+    }
+    const location = response.headers.get('location');
+    if (!location) throw new ClientError(`The ${label} at ${current} returned a redirect without a location`);
+    current = validateHttpsUrl(new URL(location, current).href, `${label} redirect`);
+  }
+  throw new ClientError(`The ${label} redirected too many times`);
+}
+
+async function readBoundedBody(response, { limit, label }) {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > limit) throw new ClientError(`The ${label} exceeds ${limit} bytes`);
+  if (!response.body) throw new ClientError(`The ${label} returned no body`);
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > limit) {
+        await reader.cancel();
+        throw new ClientError(`The ${label} exceeds ${limit} bytes`);
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } catch (error) {
+    if (error instanceof ClientError) throw error;
+    throw new ClientError(`Cannot read ${label}: ${error.message}`);
+  }
+  return Buffer.concat(chunks, length);
+}
+
+export async function fetchReleaseCatalog(catalogUrl, fetchImpl = globalThis.fetch) {
+  const resolved = validateCatalogUrl(catalogUrl);
+  const { response, finalUrl } = await fetchHttps(
+    resolved,
+    { timeout: 15_000, label: 'platform release catalog' },
+    fetchImpl,
+  );
+  if (!response.ok) throw new ClientError(`Platform release catalog at ${finalUrl} returned HTTP ${response.status}`);
+  const bytes = await readBoundedBody(response, { limit: MAX_CATALOG_BYTES, label: 'platform release catalog' });
+  let value;
+  try {
+    value = JSON.parse(bytes.toString('utf8'));
+  } catch (error) {
+    throw new ClientError(`Invalid JSON in platform release catalog at ${finalUrl}: ${error.message}`);
+  }
+  return parseReleaseCatalog(value, finalUrl);
+}
+
+async function downloadArtifact(source, fetchImpl = globalThis.fetch) {
+  const { response, finalUrl } = await fetchHttps(
+    source.artifactUrl,
+    { timeout: 60_000, label: 'platform release' },
+    fetchImpl,
+  );
+  if (!response.ok) throw new ClientError(`Platform release ${finalUrl} returned HTTP ${response.status}`);
+  const bytes = await readBoundedBody(response, { limit: MAX_ARTIFACT_BYTES, label: 'platform release' });
+  const observed = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (observed !== source.artifactSha256) {
+    throw new ClientError(`Platform release digest mismatch: expected ${source.artifactSha256}, received ${observed}`);
+  }
+  return { bytes, artifactUrl: finalUrl };
+}
+
+function readLocalArtifact(source) {
+  const resolved = path.resolve(source);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(resolved, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) throw new ClientError(`Platform release must be a regular local file: ${resolved}`);
+    if (stat.size > MAX_ARTIFACT_BYTES) throw new ClientError(`Platform release exceeds ${MAX_ARTIFACT_BYTES} bytes`);
+    return { path: resolved, bytes: fs.readFileSync(descriptor) };
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new ClientError(`Platform release does not exist: ${resolved}`);
+    if (error instanceof ClientError) throw error;
+    throw new ClientError(`Cannot read platform release ${resolved}: ${error.message}`);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+function updaterPath(env) {
+  if (env.NODE_ENV === 'test' && env.EMPTYOS_TEST_PLATFORM_UPDATER) return env.EMPTYOS_TEST_PLATFORM_UPDATER;
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'provision', 'update-platform.sh');
+}
+
+function readUpdaterResult(resultFile) {
+  if (!fs.existsSync(resultFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function reconciliationNextCommand(selected, update) {
+  if (update?.status !== 'needs-reconciliation' ||
+      !/^stage\.[A-Za-z0-9]{1,64}$/.test(update.retainedStage ?? '')) return null;
+  return `empty --computer ${selected.alias} computer update --resume ${update.retainedStage}`;
+}
+
+export async function updateComputer(selected, options, { env, stdout, stderr, fetchImpl = globalThis.fetch }) {
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'empty-client-platform-update.'));
+  const artifactFile = path.join(stage, 'release.json');
+  const resultFile = path.join(stage, 'result.json');
+  try {
+    const transport = sshTransport(selected, env);
+    const transportArgs = ['--ssh-command', sshCommand(env)];
+    for (const option of transport.options) transportArgs.push('--ssh-option', option);
+    const command = updaterPath(env);
+
+    if (options.resume) {
+      const args = [
+        ...transportArgs,
+        '--resume', options.resume,
+        '--result-file', resultFile,
+        selected.target,
+      ];
+      if (options.json) {
+        const result = await runCaptured(command, args, { env });
+        const update = readUpdaterResult(resultFile);
+        const exitCode = result.code === 0 && update === null ? 1 : result.code;
+        stdout.write(`${JSON.stringify({
+          computer: selected.alias,
+          target: selected.target,
+          mode: 'resume',
+          retainedStage: options.resume,
+          ...(update?.release ? { release: update.release } : {}),
+          source: { type: 'retained-stage', stage: options.resume },
+          ok: exitCode === 0,
+          exitCode,
+          status: update?.status ?? 'failed',
+          plan: update,
+          output: result.stdout,
+          warnings: `${result.stderr}${result.code === 0 && update === null ? 'Platform updater returned no structured result\n' : ''}`,
+        })}\n`);
+        return exitCode;
+      }
+
+      stdout.write(`Resuming computer ${selected.alias} update from ${options.resume}\n`);
+      const exitCode = await runInherited(command, args, { env });
+      if (exitCode === 0 && readUpdaterResult(resultFile) === null) {
+        throw new ClientError('Platform updater returned no structured result');
+      }
+      return exitCode;
+    }
+
+    let source;
+    let artifactBytes;
+    if (options.release) {
+      const local = readLocalArtifact(options.release);
+      artifactBytes = local.bytes;
+      source = { type: 'local', path: local.path };
+    } else {
+      const catalogUrl = options.catalog ?? selected.releaseCatalog ?? PLATFORM_RELEASE_CATALOG_URL;
+      const catalog = await fetchReleaseCatalog(catalogUrl, fetchImpl);
+      const downloaded = await downloadArtifact(catalog, fetchImpl);
+      artifactBytes = downloaded.bytes;
+      source = { type: 'catalog', ...catalog, artifactUrl: downloaded.artifactUrl };
+    }
+
+    let release;
+    try {
+      release = parseReleaseArtifactBytes(
+        artifactBytes,
+        source.type === 'local' ? source.path : source.artifactUrl,
+      );
+    } catch (error) {
+      throw new ClientError(`Invalid platform release: ${error.message}`);
+    }
+    const artifactSha256 = release.artifactSha256;
+    fs.writeFileSync(artifactFile, artifactBytes, { mode: 0o600, flag: 'wx' });
+    fs.chmodSync(artifactFile, 0o400);
+    const args = [];
+    if (!options.check) args.push('--apply');
+    args.push(...transportArgs);
+    args.push('--release', artifactFile, '--result-file', resultFile, selected.target);
+
+    if (options.json) {
+      const result = await runCaptured(command, args, { env });
+      const update = readUpdaterResult(resultFile);
+      const exitCode = result.code === 0 && update === null ? 1 : result.code;
+      const nextCommand = reconciliationNextCommand(selected, update);
+      stdout.write(`${JSON.stringify({
+        computer: selected.alias,
+        target: selected.target,
+        mode: options.check ? 'check' : 'apply',
+        release: release.release,
+        artifactSha256,
+        source,
+        ok: exitCode === 0,
+        exitCode,
+        status: update?.status ?? 'failed',
+        plan: update,
+        ...(nextCommand ? { nextCommand } : {}),
+        output: result.stdout,
+        warnings: `${result.stderr}${result.code === 0 && update === null ? 'Platform updater returned no structured result\n' : ''}`,
+      })}\n`);
+      return exitCode;
+    }
+
+    stdout.write(`${options.check ? 'Checking' : 'Updating'} computer ${selected.alias} to ${release.release}\n`);
+    if (source.type === 'catalog') {
+      stdout.write(`Catalog: ${source.catalogUrl}\nArtifact: ${source.artifactUrl}\nDigest: ${artifactSha256}\n`);
+    } else {
+      stdout.write(`Release: ${source.path}\nDigest: ${artifactSha256}\n`);
+    }
+    const exitCode = await runInherited(command, args, { env });
+    const update = readUpdaterResult(resultFile);
+    if (exitCode === 0 && update === null) {
+      throw new ClientError('Platform updater returned no structured result');
+    }
+    const nextCommand = reconciliationNextCommand(selected, update);
+    if (nextCommand) {
+      stdout.write('\nThis update needs a file-level reconciliation; continue from an agent so it can inspect and merge the retained candidate, then run:\n');
+      stdout.write(`  ${nextCommand}\n`);
+    }
+    return exitCode;
+  } finally {
+    try {
+      fs.rmSync(stage, { recursive: true, force: true });
+    } catch {
+      // Owner-only temporary release bytes are safe to leave for OS cleanup.
+    }
+  }
+}

package/lib/process.js

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+export function runInherited(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { ...options, stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code, signal) => resolve(code ?? signalExitCode(signal)));
+  });
+}
+
+export function runCaptured(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { ...options, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => (stdout += chunk));
+    child.stderr.on('data', (chunk) => (stderr += chunk));
+    child.once('error', reject);
+    child.once('close', (code, signal) => resolve({ code: code ?? signalExitCode(signal), stdout, stderr }));
+  });
+}
+
+export function runFileCaptured(command, args, inputFile, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { ...options, stdio: ['pipe', 'pipe', 'pipe'] });
+    const input = fs.createReadStream(inputFile);
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => (stdout += chunk));
+    child.stderr.on('data', (chunk) => (stderr += chunk));
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      input.destroy();
+      child.kill();
+      reject(error);
+    };
+
+    child.once('error', fail);
+    input.once('error', fail);
+    child.stdin.once('error', (error) => {
+      // A remote validation failure may close stdin before the local bundle
+      // finishes streaming. Its exit status and structured output win.
+      if (error.code !== 'EPIPE') fail(error);
+    });
+    child.once('close', (code, signal) => {
+      if (settled) return;
+      settled = true;
+      input.destroy();
+      resolve({ code: code ?? signalExitCode(signal), stdout, stderr });
+    });
+    input.pipe(child.stdin);
+  });
+}
+
+export function runFileInherited(command, args, inputFile, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { ...options, stdio: ['pipe', 'inherit', 'inherit'] });
+    const input = fs.createReadStream(inputFile);
+    let settled = false;
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      input.destroy();
+      child.kill();
+      reject(error);
+    };
+
+    child.once('error', fail);
+    input.once('error', fail);
+    child.stdin.once('error', (error) => {
+      // A remote validation failure may close stdin before the local bundle
+      // finishes streaming. Its exit status and stderr are authoritative.
+      if (error.code !== 'EPIPE') fail(error);
+    });
+    child.once('close', (code, signal) => {
+      if (settled) return;
+      settled = true;
+      input.destroy();
+      resolve(code ?? signalExitCode(signal));
+    });
+    input.pipe(child.stdin);
+  });
+}
+
+function signalExitCode(signal) {
+  return signal ? 1 : 0;
+}

package/lib/rpc.js

@@ -0,0 +1,161 @@
+import { PROTOCOL_VERSION } from './constants.js';
+import { ClientError } from './errors.js';
+import { runCaptured, runFileCaptured, runFileInherited, runInherited } from './process.js';
+
+// OpenSSH exits 255 for its own failures (tunnel, host key, authentication);
+// resident commands exit 0-254.
+const SSH_TRANSPORT_EXIT = 255;
+
+export function encodeRequest(argv) {
+  return Buffer.from(JSON.stringify({ protocolVersion: PROTOCOL_VERSION, argv }), 'utf8').toString('base64url');
+}
+
+export function sshRpcArgs(target, argv) {
+  const payload = encodeRequest(argv);
+  // The only dynamic shell token is base64url data produced above. User text
+  // exists exclusively inside the encoded JSON payload.
+  const remoteCommand = `$HOME/.local/bin/empty client-exec ${payload}`;
+  return ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-T', target, remoteCommand];
+}
+
+export function rpcInherited(profile, argv, env = process.env) {
+  const transport = sshTransport(profile, env);
+  return explainTransportExit(
+    withTransportError(runInherited(sshCommand(env), [...transport.options, ...sshRpcArgs(transport.target, argv)], { env }), transport.target),
+    profile,
+    transport.target,
+  );
+}
+
+export function rpcCaptured(profile, argv, env = process.env) {
+  const transport = sshTransport(profile, env);
+  return attachTransportHint(
+    withTransportError(runCaptured(sshCommand(env), [...transport.options, ...sshRpcArgs(transport.target, argv)], { env }), transport.target),
+    profile,
+    transport.target,
+  );
+}
+
+export function rpcFileInherited(profile, argv, inputFile, env = process.env) {
+  const transport = sshTransport(profile, env);
+  const payload = encodeRequest(argv);
+  // Metadata remains structured and shell-safe while the Git bundle streams
+  // over stdin without entering the bounded argv protocol payload.
+  const remoteCommand = `$HOME/.local/bin/empty client-import ${payload}`;
+  const args = [
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+    '-o', 'ServerAliveInterval=15',
+    '-o', 'ServerAliveCountMax=3',
+    ...transport.options,
+    '-T', transport.target, remoteCommand,
+  ];
+  return explainTransportExit(
+    withTransportError(runFileInherited(sshCommand(env), args, inputFile, { env }), transport.target),
+    profile,
+    transport.target,
+  );
+}
+
+export function rpcFileCaptured(profile, argv, inputFile, env = process.env) {
+  const transport = sshTransport(profile, env);
+  const payload = encodeRequest(argv);
+  const remoteCommand = `$HOME/.local/bin/empty client-import ${payload}`;
+  const args = [
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+    '-o', 'ServerAliveInterval=15',
+    '-o', 'ServerAliveCountMax=3',
+    ...transport.options,
+    '-T', transport.target, remoteCommand,
+  ];
+  return attachTransportHint(
+    withTransportError(runFileCaptured(sshCommand(env), args, inputFile, { env }), transport.target),
+    profile,
+    transport.target,
+  );
+}
+
+export function rawSsh(profile, argv, env = process.env) {
+  const transport = sshTransport(profile, env);
+  const args = argv.length === 0
+    ? [...transport.options, transport.target]
+    : [...transport.options, '-T', transport.target, ...argv];
+  return runInherited(sshCommand(env), args, { env });
+}
+
+export function sshTransport(profile, env = process.env) {
+  if (typeof profile === 'string') return { target: profile, options: [] };
+  if (!profile?.ownerOrigin) return { target: profile.target, options: [] };
+
+  const proxyCommand = [
+    process.execPath,
+    process.argv[1],
+    '__ssh-tunnel',
+    profile.ownerOrigin,
+    profile.tunnelTokenPath,
+  ].map(shellQuoteForProxyCommand).join(' ');
+  const hostKeyAlias = new URL(profile.ownerOrigin).hostname;
+  return {
+    target: profile.target,
+    options: [
+      '-F', '/dev/null',
+      '-i', profile.sshIdentityPath,
+      '-o', 'IdentitiesOnly=yes',
+      '-o', 'StrictHostKeyChecking=yes',
+      '-o', `UserKnownHostsFile=${profile.sshKnownHostsPath}`,
+      '-o', 'GlobalKnownHostsFile=/dev/null',
+      '-o', 'ControlMaster=no',
+      '-o', 'ControlPath=none',
+      '-o', `HostKeyAlias=${hostKeyAlias}`,
+      '-o', `ProxyCommand=${proxyCommand}`,
+    ],
+  };
+}
+
+function shellQuoteForProxyCommand(value) {
+  // OpenSSH expands percent tokens before invoking the ProxyCommand shell.
+  // Doubling them preserves literal percent characters inside paths and URLs.
+  const literal = String(value).replaceAll('%', '%%');
+  return `'${literal.replaceAll("'", "'\\''")}'`;
+}
+
+export function sshCommand(env) {
+  return env.EMPTYOS_SSH_COMMAND || 'ssh';
+}
+
+// ssh (and the tunnel helper it runs) has already written the failure detail
+// to stderr; the hint naming the profile is the part only the client can add,
+// set off by a blank line from that detail.
+function transportHint(profile, target) {
+  const alias = typeof profile === 'string' ? null : profile.alias ?? null;
+  return alias
+    ? `\nempty: Could not connect to computer ${JSON.stringify(alias)}; list computers with \`empty computers\` or forget this one with \`empty computer remove ${alias}\`\n`
+    : `\nempty: Could not connect to computer ${JSON.stringify(target)}\n`;
+}
+
+async function explainTransportExit(operation, profile, target, stderr = process.stderr) {
+  const code = await operation;
+  if (code === SSH_TRANSPORT_EXIT) stderr.write(transportHint(profile, target));
+  return code;
+}
+
+// Captured results are relayed later; human-mode relays print the hint after
+// the captured stderr, JSON relays keep it out of the structured error.
+async function attachTransportHint(operation, profile, target) {
+  const result = await operation;
+  if (result.code === SSH_TRANSPORT_EXIT) result.transportHint = transportHint(profile, target);
+  return result;
+}
+
+async function withTransportError(operation, target) {
+  try {
+    return await operation;
+  } catch (error) {
+    if (error instanceof ClientError) throw error;
+    throw new ClientError(
+      `Cannot connect to EmptyOS computer ${JSON.stringify(target)}: ${error.message}; check SSH connectivity and retry`,
+      'transport-failed',
+    );
+  }
+}

package/lib/skill-install.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { ClientError } from './errors.js';
+
+export const SKILL_ID = 'emptyos-computer';
+const BUNDLED_SKILL = fileURLToPath(new URL(`../skills/${SKILL_ID}/`, import.meta.url));
+
+export function defaultSkillsDir(env = process.env) {
+  return path.join(env.HOME || os.homedir(), '.agents', 'skills');
+}
+
+// Copies the bundled skill directory to <dir>/emptyos-computer/. Existing
+// files are replaced without asking: the skill is the client's own file and
+// is versioned with it.
+export function installSkill(dir, { platform = process.platform } = {}) {
+  if (platform === 'win32') throw new ClientError('`skill install` supports macOS and Linux only');
+  const target = path.join(path.resolve(dir), SKILL_ID);
+  for (const relative of bundledFiles()) {
+    const destination = path.join(target, relative);
+    try {
+      fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 });
+    } catch (error) {
+      throw new ClientError(`Cannot create ${path.dirname(destination)}: ${error.message}`);
+    }
+    replaceFile(destination, fs.readFileSync(path.join(BUNDLED_SKILL, relative)));
+  }
+  return target;
+}
+
+function bundledFiles(prefix = '') {
+  const entries = fs.readdirSync(path.join(BUNDLED_SKILL, prefix), { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const files = [];
+  for (const entry of entries) {
+    const relative = path.join(prefix, entry.name);
+    if (entry.isDirectory()) files.push(...bundledFiles(relative));
+    else if (entry.isFile()) files.push(relative);
+    else throw new ClientError(`Bundled skill contains an unsupported entry: ${relative}`);
+  }
+  return files;
+}
+
+function replaceFile(file, contents) {
+  const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(temp, 'wx', 0o644);
+    fs.writeFileSync(fd, contents);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temp, file);
+  } catch (error) {
+    if (fd !== undefined) fs.closeSync(fd);
+    try {
+      fs.unlinkSync(temp);
+    } catch (unlinkError) {
+      if (unlinkError.code !== 'ENOENT') throw unlinkError;
+    }
+    throw new ClientError(`Cannot write ${file}: ${error.message}`);
+  }
+}