@emptyos/client 0.1.0

package/lib/thing-put.js

@@ -0,0 +1,406 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { ClientError } from './errors.js';
+import { gitCaptured } from './git.js';
+import { readThingMetadata } from './manifest.js';
+
+const VCS_DIRECTORIES = new Set(['.git', '.hg', '.svn']);
+
+const GITIGNORE = `# Dependencies and generated output
+node_modules/
+build/
+.cache/
+
+# Local configuration and secrets
+.env
+.env.*
+!.env.example
+
+# Durable or test data
+*.sqlite
+*.sqlite3
+*.db
+
+# Runtime state
+*.log
+*.pid
+coverage/
+`;
+
+const GITATTRIBUTES = `# Preserve imported bytes on every workstation and computer.
+* -text
+`;
+
+export function inspectGeneratedSource(sourcePath) {
+  const source = path.resolve(sourcePath);
+  let stat;
+  try {
+    stat = fs.lstatSync(source);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new ClientError(`Source does not exist: ${source}`, 'source-missing');
+    throw error;
+  }
+  if (stat.isSymbolicLink()) throw new ClientError(`Source must not be a symbolic link: ${source}`, 'source-symlink');
+  if (stat.isDirectory()) {
+    if (fs.existsSync(path.join(source, 'thing.yaml'))) return { source, stat, kind: 'manifested-thing' };
+    const index = path.join(source, 'index.html');
+    let indexStat;
+    try {
+      indexStat = fs.lstatSync(index);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new ClientError(
+          `${source} does not look like a ready static site: no root index.html; put its build output, or add thing.yaml to declare a Thing`,
+          'ambiguous-directory',
+        );
+      }
+      throw error;
+    }
+    if (indexStat.isSymbolicLink() || !indexStat.isFile()) {
+      throw new ClientError(`Static site index.html must be a regular file, not a symlink: ${index}`, 'invalid-static-index');
+    }
+    return { source, stat, kind: 'static-directory' };
+  }
+  if (!stat.isFile()) throw new ClientError(`Source must be a regular file or directory: ${source}`, 'invalid-source-type');
+  const extension = path.extname(source).toLowerCase();
+  return { source, stat, kind: extension === '.html' || extension === '.htm' ? 'html-file' : 'declared-file' };
+}
+
+export function derivedThingId(source, kind) {
+  const basename = path.basename(source);
+  return kind === 'static-directory' || kind === 'manifested-thing'
+    ? basename
+    : basename.slice(0, basename.length - path.extname(basename).length);
+}
+
+export async function stageGeneratedThing(sourceInfo, id, name, {
+  env = process.env,
+  projectId = null,
+  visibility = 'private',
+} = {}) {
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'empty-put-'));
+  const repo = path.join(stage, 'repo');
+  const publicDir = path.join(repo, 'public');
+  const bundle = path.join(stage, 'thing.bundle');
+  const stats = { fileCount: 0, byteCount: 0 };
+  try {
+    if (sourceInfo.kind === 'manifested-thing') {
+      await snapshotManifestedThing(sourceInfo.source, repo, stats, env, sourceInfo.manifested ?? null);
+      return await packageRepo(stage, repo, bundle, name, stats, sourceInfo.kind, env);
+    }
+    fs.mkdirSync(publicDir, { recursive: true });
+    let declaredFile = null;
+    if (sourceInfo.kind === 'static-directory') {
+      copyTree(sourceInfo.source, publicDir, stats, sourceInfo.stat);
+    } else if (sourceInfo.kind === 'html-file') {
+      copyRegularFile(sourceInfo.source, path.join(publicDir, 'index.html'), stats);
+    } else {
+      declaredFile = path.basename(sourceInfo.source);
+      validateFilename(declaredFile);
+      copyRegularFile(sourceInfo.source, path.join(publicDir, declaredFile), stats);
+    }
+
+    const projectLine = projectId === null ? '' : `project: ${JSON.stringify(projectId)}\n`;
+    const fileLine = declaredFile === null ? '' : `file: ${JSON.stringify(declaredFile)}\n`;
+    fs.writeFileSync(
+      path.join(repo, 'thing.yaml'),
+      `id: ${JSON.stringify(id)}\nname: ${JSON.stringify(name)}\ntype: static\ndirectory: public\n${fileLine}route: ${JSON.stringify(`/${id}`)}\nvisibility: ${visibility}\n${projectLine}`,
+    );
+    fs.writeFileSync(path.join(repo, '.gitignore'), GITIGNORE);
+    fs.writeFileSync(path.join(repo, '.gitattributes'), GITATTRIBUTES);
+    const required = declaredFile === null ? 'public/index.html' : `public/${declaredFile}`;
+    fs.writeFileSync(
+      path.join(repo, 'verify'),
+      `#!/bin/sh\nset -eu\nfile=${shellQuote(required)}\ntest -f thing.yaml\ntest -f "$file"\ntest ! -L "$file"\n`,
+      { mode: 0o755 },
+    );
+
+    return await packageRepo(stage, repo, bundle, name, stats, sourceInfo.kind, env);
+  } catch (error) {
+    cleanPutStage(stage);
+    throw error;
+  }
+}
+
+export async function inspectManifestedSource(source, env = process.env) {
+  const root = (await gitMust(['-C', source, 'rev-parse', '--show-toplevel'], env, 'Putting a manifested Thing requires a Git repository')).trim();
+  if (fs.realpathSync(root) !== fs.realpathSync(source)) {
+    throw new ClientError(`thing.yaml must be at the root of the Git repository (repository root: ${root})`, 'manifest-not-repository-root');
+  }
+  const branch = await gitResult(
+    ['-C', source, 'symbolic-ref', '--quiet', '--short', 'HEAD'],
+    env,
+    'cannot inspect the manifested Thing branch',
+  );
+  if (branch.code !== 0 || !branch.stdout.trim()) {
+    throw new ClientError('Putting a manifested Thing requires an attached Git branch', 'detached-head');
+  }
+  const status = await gitMust(['-C', source, 'status', '--porcelain', '--untracked-files=all'], env, 'Cannot inspect the manifested Thing');
+  if (status !== '') throw new ClientError('Putting a manifested Thing requires a clean worktree with no tracked or untracked changes', 'dirty-worktree');
+  const head = (await gitMust(['-C', source, 'rev-parse', 'HEAD'], env, 'Cannot resolve the manifested Thing commit')).trim();
+  const manifest = readThingMetadata(source);
+  for (const script of ['verify', 'prepare']) {
+    const tracked = await gitResult(
+      ['-C', source, 'ls-files', '--error-unmatch', '--', script],
+      env,
+      `cannot inspect manifested ./${script}`,
+    );
+    if (script === 'prepare' && tracked.code !== 0) continue;
+    if (tracked.code !== 0) throw new ClientError('Putting a manifested Thing requires ./verify to be tracked by Git', 'verify-untracked');
+    validateExecutable(path.join(source, script), script);
+  }
+  const finalHead = (await gitMust(['-C', source, 'rev-parse', 'HEAD'], env, 'Cannot recheck the manifested Thing commit')).trim();
+  const finalStatus = await gitMust(['-C', source, 'status', '--porcelain', '--untracked-files=all'], env, 'Cannot recheck the manifested Thing');
+  if (finalHead !== head || finalStatus !== '') {
+    throw new ClientError('Manifested Thing changed during preflight; finish the change and retry', 'source-changed');
+  }
+  return { ...manifest, head };
+}
+
+export function cleanPutStage(stage) {
+  try {
+    fs.rmSync(stage, { recursive: true, force: true });
+  } catch {
+    // The OS can reap this non-canonical workstation staging directory.
+  }
+}
+
+function copyTree(source, destination, stats, expected = lstatTreeEntry(source)) {
+  assertStableDirectory(source, expected, 'before');
+  let entries;
+  try {
+    entries = fs.readdirSync(source, { withFileTypes: true });
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) {
+      throw new ClientError(`Source directory changed while EmptyOS copied it: ${source}`, 'source-changed');
+    }
+    throw error;
+  }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const from = path.join(source, entry.name);
+    const to = path.join(destination, entry.name);
+    const stat = lstatTreeEntry(from);
+    if (stat.isSymbolicLink()) throw new ClientError(`Static site must not contain symbolic links: ${from}`, 'source-symlink');
+    if (VCS_DIRECTORIES.has(entry.name) && stat.isDirectory()) continue;
+    if (stat.isDirectory()) {
+      fs.mkdirSync(to, { mode: stat.mode & 0o777 });
+      copyTree(from, to, stats, stat);
+    } else if (stat.isFile()) {
+      copyRegularFile(from, to, stats, stat);
+    } else {
+      throw new ClientError(`Static site contains an unsupported special file: ${from}`, 'invalid-source-type');
+    }
+  }
+  assertStableDirectory(source, expected, 'while');
+}
+
+async function snapshotManifestedThing(source, destination, stats, env, expected) {
+  const inspected = await inspectManifestedSource(source, env);
+  if (expected && inspected.head !== expected.head) {
+    throw new ClientError('Manifested Thing changed after preflight; retry the put', 'source-changed');
+  }
+  const head = expected?.head ?? inspected.head;
+  fs.mkdirSync(destination, { recursive: true });
+  const tree = await gitMust(['-C', source, 'ls-tree', '-r', '-z', '--full-tree', head], isolatedGitEnv(env), 'Cannot enumerate the manifested Thing');
+  for (const record of tree.split('\0')) {
+    if (!record) continue;
+    const tab = record.indexOf('\t');
+    const header = tab === -1 ? '' : record.slice(0, tab);
+    const relative = tab === -1 ? '' : record.slice(tab + 1);
+    const match = /^(100644|100755) blob ([0-9a-f]{40}|[0-9a-f]{64})$/.exec(header);
+    if (!match) throw new ClientError(`Manifested Thing contains an unsupported Git entry: ${relative || header}`, 'invalid-source-type');
+    if (!safeGitPath(relative)) throw new ClientError(`Manifested Thing contains an unsafe path: ${JSON.stringify(relative)}`, 'invalid-source-path');
+    const file = path.join(destination, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    await writeGitBlob(source, match[2], file, match[1] === '100755' ? 0o755 : 0o644, env);
+  }
+  inspectCopiedTree(destination, stats);
+  const final = await inspectManifestedSource(source, env);
+  if (final.head !== head) throw new ClientError('Manifested Thing changed while EmptyOS copied it; retry the put', 'source-changed');
+}
+
+function safeGitPath(relative) {
+  if (!relative || path.isAbsolute(relative) || relative.includes('\0')) return false;
+  const parts = relative.split('/');
+  return parts.every((part) => part !== '' && part !== '.' && part !== '..');
+}
+
+async function writeGitBlob(source, object, destination, mode, env) {
+  const gitEnv = isolatedGitEnv(env);
+  const command = gitEnv.EMPTYOS_GIT_COMMAND || 'git';
+  const child = spawn(command, ['-C', source, 'cat-file', 'blob', object], {
+    env: gitEnv,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => (stderr += chunk));
+  const exited = new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new ClientError(stderr.trim() || `cannot read Git object ${object}${signal ? ` (${signal})` : ''}`, 'git-failed'));
+    });
+  });
+  try {
+    await Promise.all([
+      pipeline(child.stdout, fs.createWriteStream(destination, { flags: 'wx', mode })),
+      exited,
+    ]);
+    fs.chmodSync(destination, mode);
+  } catch (error) {
+    child.kill();
+    fs.rmSync(destination, { force: true });
+    throw error;
+  }
+}
+
+function inspectCopiedTree(root, stats, current = root) {
+  for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+    const file = path.join(current, entry.name);
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) throw new ClientError(`Manifested Thing must not contain symbolic links: ${file}`, 'source-symlink');
+    if (stat.isDirectory()) inspectCopiedTree(root, stats, file);
+    else if (stat.isFile()) {
+      stats.fileCount += 1;
+      stats.byteCount += stat.size;
+    } else throw new ClientError(`Manifested Thing contains an unsupported special file: ${file}`, 'invalid-source-type');
+  }
+}
+
+function validateExecutable(file, name) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new ClientError(`Putting a manifested Thing requires ./${name}`, `${name}-missing`);
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile() || (stat.mode & 0o111) === 0) {
+    throw new ClientError(`./${name} must be an executable regular file, not a symlink`, `${name}-invalid`);
+  }
+}
+
+async function packageRepo(stage, repo, bundle, name, stats, sourceKind, env) {
+  const gitEnv = isolatedGitEnv(env);
+  const template = path.join(stage, 'git-template');
+  fs.mkdirSync(template);
+  await gitMust(['init', '--quiet', '--initial-branch=main', `--template=${template}`, repo], gitEnv, 'Cannot initialize the Thing');
+  for (const [key, value] of [
+    ['user.name', 'EmptyOS'],
+    ['user.email', 'emptyos@localhost'],
+    ['core.autocrlf', 'false'],
+    ['core.safecrlf', 'false'],
+    ['core.hooksPath', os.devNull],
+    ['commit.gpgSign', 'false'],
+  ]) {
+    await gitMust(['-C', repo, 'config', '--local', key, value], gitEnv, 'Cannot isolate the Thing repository');
+  }
+  await gitMust(['-C', repo, 'add', '-A', '-f'], gitEnv, 'Cannot stage the Thing');
+  await gitMust(['-C', repo, 'commit', '--quiet', '--no-gpg-sign', '-m', `Create ${name}`], gitEnv, 'Cannot commit the Thing');
+  const head = (await gitMust(['-C', repo, 'rev-parse', 'HEAD'], gitEnv, 'Cannot resolve the Thing commit')).trim();
+  await gitMust(['-C', repo, 'bundle', 'create', bundle, 'main'], gitEnv, 'Cannot package the Thing');
+  return { bundle, head, stage, ...stats, sourceKind };
+}
+
+function copyRegularFile(source, destination, stats, before = fs.lstatSync(source)) {
+  if (before.isSymbolicLink() || !before.isFile()) {
+    throw new ClientError(`Source must be a regular file, not a symlink: ${source}`, 'invalid-source-type');
+  }
+  let sourceFd;
+  let destinationFd;
+  try {
+    try {
+      sourceFd = fs.openSync(source, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    } catch (error) {
+      if (error.code === 'ELOOP') throw new ClientError(`Source changed before EmptyOS could copy it: ${source}`, 'source-changed');
+      throw error;
+    }
+    const opened = fs.fstatSync(sourceFd);
+    if (!sameFileSnapshot(before, opened)) throw new ClientError(`Source changed before EmptyOS could copy it: ${source}`, 'source-changed');
+    destinationFd = fs.openSync(destination, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, before.mode & 0o777);
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    for (;;) {
+      const read = fs.readSync(sourceFd, buffer, 0, buffer.length, null);
+      if (read === 0) break;
+      let written = 0;
+      while (written < read) written += fs.writeSync(destinationFd, buffer, written, read - written);
+    }
+    const after = fs.fstatSync(sourceFd);
+    if (!sameFileSnapshot(opened, after)) throw new ClientError(`Source changed while EmptyOS copied it: ${source}`, 'source-changed');
+    fs.fchmodSync(destinationFd, before.mode & 0o777);
+  } finally {
+    if (destinationFd !== undefined) fs.closeSync(destinationFd);
+    if (sourceFd !== undefined) fs.closeSync(sourceFd);
+  }
+  stats.fileCount += 1;
+  stats.byteCount += before.size;
+}
+
+function sameFileSnapshot(left, right) {
+  return left.isFile() && right.isFile() && left.dev === right.dev && left.ino === right.ino &&
+    left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+
+function lstatTreeEntry(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new ClientError(`Source changed while EmptyOS copied it: ${file}`, 'source-changed');
+    throw error;
+  }
+}
+
+function assertStableDirectory(directory, expected, timing) {
+  const current = lstatTreeEntry(directory);
+  if (!current.isDirectory() || !sameDirectorySnapshot(expected, current)) {
+    throw new ClientError(`Source directory changed ${timing} EmptyOS copied it: ${directory}`, 'source-changed');
+  }
+}
+
+function sameDirectorySnapshot(left, right) {
+  return left.isDirectory() && right.isDirectory() && left.dev === right.dev && left.ino === right.ino &&
+    left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+
+function validateFilename(filename) {
+  if (!filename || filename === '.' || filename === '..' || /[\u0000-\u001f\u007f]/.test(filename)) {
+    throw new ClientError(`Unsupported file name: ${JSON.stringify(filename)}`, 'invalid-source-name');
+  }
+}
+
+async function gitMust(args, env, fallback) {
+  const result = await gitResult(args, env, fallback);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new ClientError(detail ? `${fallback}: ${detail}` : fallback, 'git-failed');
+  }
+  return result.stdout;
+}
+
+async function gitResult(args, env, fallback) {
+  try {
+    return await gitCaptured(args, { env });
+  } catch (error) {
+    throw new ClientError(`${fallback}: ${error.message}`, 'git-failed');
+  }
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function isolatedGitEnv(env) {
+  const clean = {};
+  for (const [key, value] of Object.entries(env)) if (!key.startsWith('GIT_')) clean[key] = value;
+  return {
+    ...clean,
+    GIT_ATTR_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: os.devNull,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_SYSTEM: os.devNull,
+  };
+}

package/lib/tunnel-proxy.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import https from 'node:https';
+import { constants as fsConstants } from 'node:fs';
+import { ClientError } from './errors.js';
+
+const TUNNEL_PATH = '/_system/ssh';
+const TUNNEL_PROTOCOL = 'emptyos-ssh';
+// Shorter than the client's ssh ConnectTimeout=10 so this helper explains a
+// silent host before ssh gives up on the banner exchange and kills it.
+const TUNNEL_CONNECT_TIMEOUT_MS = 8_000;
+const UNANSWERED_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE']);
+const TLS_CODE_RE = /^(ERR_TLS_|ERR_SSL_|CERT_|UNABLE_TO_|SELF_SIGNED_|DEPTH_ZERO_)/u;
+
+export function readTunnelToken(tokenPath) {
+  let fd;
+  try {
+    fd = fs.openSync(tokenPath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o777) !== 0o600) {
+      throw new ClientError('SSH tunnel token file must be a regular file with mode 0600');
+    }
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+      throw new ClientError('SSH tunnel token file must be owned by the current user');
+    }
+    const raw = fs.readFileSync(fd, 'utf8');
+    const token = raw.trim();
+    if (!/^v1\.[A-Za-z0-9_-]{43}$/u.test(token) || (raw !== token && raw !== `${token}\n`)) {
+      throw new ClientError('SSH tunnel token file is malformed');
+    }
+    return token;
+  } catch (error) {
+    if (error instanceof ClientError) throw error;
+    throw new ClientError(`Cannot read SSH tunnel token file: ${error.message}`);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export function runTunnelProxy(
+  ownerOrigin,
+  tokenPath,
+  { stdin = process.stdin, stdout = process.stdout, request = https.request } = {},
+) {
+  const token = readTunnelToken(tokenPath);
+  const url = new URL(TUNNEL_PATH, ownerOrigin);
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      reject(error instanceof ClientError ? error : new ClientError(describeTunnelError(url.hostname, error)));
+    };
+    const req = request(url, {
+      method: 'GET',
+      agent: false,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Connection: 'Upgrade',
+        Upgrade: TUNNEL_PROTOCOL,
+      },
+    });
+
+    req.once('response', (response) => {
+      response.resume();
+      fail(new ClientError(describeTunnelStatus(url.hostname, response.statusCode ?? 0)));
+    });
+    req.once('upgrade', (response, socket, head) => {
+      if (response.statusCode !== 101 || response.headers.upgrade?.toLowerCase() !== TUNNEL_PROTOCOL) {
+        socket.destroy();
+        fail(new ClientError('SSH tunnel endpoint returned an invalid protocol upgrade'));
+        return;
+      }
+      if (settled) {
+        socket.destroy();
+        return;
+      }
+      socket.setNoDelay?.(true);
+      socket.setTimeout?.(0);
+      if (head.length > 0) stdout.write(head);
+      socket.pipe(stdout, { end: false });
+      stdin.pipe(socket);
+      socket.once('error', fail);
+      socket.once('close', () => {
+        if (settled) return;
+        settled = true;
+        resolve(0);
+      });
+    });
+    req.once('error', fail);
+    req.setTimeout?.(TUNNEL_CONNECT_TIMEOUT_MS, () => req.destroy(new ClientError(
+      `Cannot reach EmptyOS computer ${url.hostname}: no response within ${TUNNEL_CONNECT_TIMEOUT_MS / 1000} seconds, so the computer or its edge may be down`,
+    )));
+    req.end();
+  });
+}
+
+// ssh relays only this helper's stderr to the person, so the explanation is
+// spelled out here; the parent client adds the alias-specific hint afterwards.
+function describeTunnelError(host, error) {
+  const code = typeof error.code === 'string' ? error.code : '';
+  const unreachable = (reason) => `Cannot reach EmptyOS computer ${host}: ${reason} (${error.message})`;
+  if (code === 'ENOTFOUND') return unreachable('its address no longer resolves, so it may be decommissioned or renamed');
+  if (code === 'EAI_AGAIN') return unreachable('DNS lookup failed; check your network connection');
+  if (UNANSWERED_CODES.has(code)) return unreachable('nothing answered at its address, so the computer or its edge may be down');
+  if (TLS_CODE_RE.test(code)) return unreachable('its TLS certificate is invalid');
+  return `SSH tunnel failed: ${error.message}`;
+}
+
+function describeTunnelStatus(host, status) {
+  if (status >= 300 && status < 400) return `SSH tunnel endpoint refused an HTTP redirect (${status})`;
+  if (status === 401 || status === 403) {
+    return `EmptyOS computer ${host} rejected this client's tunnel token (HTTP ${status}); the agent may have been removed from it`;
+  }
+  if (status === 404 || status >= 500) {
+    return `Cannot reach EmptyOS computer ${host}: its edge answered HTTP ${status} without the EmptyOS recovery service, so the computer may be stopped or still starting`;
+  }
+  return `SSH tunnel endpoint returned HTTP ${status}; expected protocol upgrade`;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@emptyos/client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "External EmptyOS client",
+  "license": "MIT",
+  "bin": {
+    "empty": "bin/empty.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://emptyos.com/docs/",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}