@emptyos/client 0.1.0

package/lib/commands.js

@@ -0,0 +1,272 @@
+const COMMANDS = [
+  command('connect', 'connect <computer-url> [--as <alias>] [--label <label>] [--no-browser]', 'Connect this client to an EmptyOS computer', 'computers', 'local', [
+    'empty connect vishal.emptyos.com',
+    'empty connect maya-chen.emptyos.com --as maya',
+    'empty connect jordan.emptyos.com --label "Jordan\'s AI Computer"',
+  ], true, 'prefix', [
+    'Options:',
+    '  --as <alias>      Local shorthand used to select this computer; defaults to the first part of its URL.',
+    '  --label <label>   This client\'s display label on the approval and approved-agent screens; defaults to this machine\'s hostname.',
+    '  --no-browser      Print the approval page URL without opening it in your default browser.',
+  ]),
+  command('computers', 'computers [--json]', 'List configured computers', 'computers', 'local'),
+  command('computer add', 'computer add <alias> --host <host> [--release-catalog <https-url>] [--json]', 'Connect an EmptyOS computer', 'computers', 'local', [
+    'empty computer add personal --host owner@personal.example',
+  ]),
+  command('computer use', 'computer use <alias> [--json]', 'Select the default computer', 'computers', 'local'),
+  command('computer show', '[--computer <alias>] computer show [--json]', 'Show the selected computer', 'computers', 'local'),
+  command('computer update', '[--computer <alias>] computer update [--check | --apply | --resume <stage-name>] [--release <local-release.json> | --catalog <https-url>] [--json]', 'Check, update, or resume reconciliation for the selected computer platform', 'computers', 'hybrid', [
+    'empty computer update --check',
+    'empty computer update --apply',
+    'empty computer update --resume stage.A1b2C3',
+    'empty --computer work computer update --release ./platform-release.json',
+  ]),
+  command('computer remove', 'computer remove <alias> [--json]', 'Remove a computer profile', 'computers', 'local'),
+
+  command('things', '[--computer <alias>] things [--json]', 'List Things on the selected computer', 'things', 'remote', [
+    'empty things',
+    'empty --computer work things --json',
+  ]),
+  command('put', '[--computer <alias>] put <path> [--as <id>] [--name <name>] [--project <project-id>] [--public] [--json]', 'Put local content on the selected computer', 'things', 'hybrid', [
+    'empty put ./portfolio --as portfolio',
+    'empty put ./olive.jpg --as olive --public',
+    'empty put .',
+  ], true, 'prefix', [
+    'A directory is the deployment boundary: every selected file becomes owner-served content and may become anonymous with --public. Prefer a ready build-output directory over a source repository root.',
+    'A manifested repository may run its tracked ./prepare as trusted owner code on the computer before offline verification.',
+  ]),
+  command('clone', '[--computer <alias>] clone <id> [directory] [--json]', 'Clone a Thing for local work', 'things', 'hybrid'),
+  command('thing describe', '[--computer <alias>] thing describe <id> [--json]', 'Inspect a Thing', 'things', 'remote'),
+  command('thing logs', '[--computer <alias>] thing logs <id> [--lines <count>] [--json]', 'Read recent service logs', 'things', 'remote'),
+  command('thing assign', '[--computer <alias>] thing assign <thing-id> <project-id> [--json]', 'Assign a Thing to a Project', 'things', 'remote'),
+  command('thing unassign', '[--computer <alias>] thing unassign <thing-id> [--json]', 'Remove a Thing from its Project', 'things', 'remote'),
+  command('thing start', '[--computer <alias>] thing start <id> [--json]', 'Start a service Thing', 'things', 'remote'),
+  command('thing stop', '[--computer <alias>] thing stop <id> [--json]', 'Stop a service Thing', 'things', 'remote'),
+  command('thing restart', '[--computer <alias>] thing restart <id> [--json]', 'Restart a service Thing', 'things', 'remote'),
+  command('thing remove', '[--computer <alias>] thing remove <id> [--json]', 'Remove a Thing service registration', 'things', 'remote'),
+  command(
+    'thing add',
+    'thing add <computer-path>',
+    'Unavailable from a workstation; use put for local content',
+    'things',
+    'unavailable',
+    [],
+    false,
+  ),
+
+  command('projects', '[--computer <alias>] projects [--json]', 'List Projects', 'projects', 'remote'),
+  command('project create', '[--computer <alias>] project create <id> <name...> [--json]', 'Create a Project', 'projects', 'remote'),
+  command('data', '[--computer <alias>] data [--json]', 'List registered Datasets', 'data', 'remote', [], true, 'json-only'),
+  command('data describe', '[--computer <alias>] data describe <id> [--json]', 'Inspect a Dataset', 'data', 'remote'),
+
+  command('status', '[--computer <alias>] status [--json]', 'Show computer health', 'system', 'remote'),
+  command('changes', '[--computer <alias>] changes [--json]', 'List committed changes', 'system', 'remote'),
+  command('commands', '[--computer <alias>] commands [--json]', 'List built-in and local commands', 'system', 'hybrid'),
+  command('hooks', '[--computer <alias>] hooks [--json]', 'List lifecycle hook events', 'system', 'remote'),
+  command('hook install', '[--computer <alias>] hook install <event> <path> [--json]', 'Install a hook from a path on the computer', 'system', 'remote'),
+  command('undo', '[--computer <alias>] undo <change-id> [--json]', 'Undo one committed change', 'system', 'remote'),
+  command('expose', '[--computer <alias>] expose <id> [--json]', 'Publish a Thing to anyone on the internet', 'system', 'remote'),
+  command('unexpose', '[--computer <alias>] unexpose <id> [--json]', 'Make a Thing private', 'system', 'remote'),
+  command('ssh', '[--computer <alias>] ssh [-- <command...>]', 'Enter the computer or run a raw command', 'system', 'hybrid'),
+  command('skill install', 'skill install [--dir <path>] [--json]', 'Install the bundled agent skill into a skills directory', 'system', 'local', [
+    'empty skill install',
+    'empty skill install --dir ~/.claude/skills',
+  ], true, 'prefix', [
+    'Copies the emptyos-computer skill that ships with this client to <dir>/emptyos-computer/, replacing an earlier copy. The default directory is ~/.agents/skills.',
+  ]),
+  command('--json', '--json', 'Show the complete computer overview as JSON', 'system', 'remote', [], true, 'exact'),
+  command('--version', '--version', 'Show the client and protocol version', 'system', 'local'),
+  command('help', 'help [command...]', 'Show command help', 'system', 'local'),
+];
+
+const SECTIONS = Object.freeze([
+  { id: 'computers', title: 'Computers' },
+  { id: 'things', title: 'Things' },
+  { id: 'projects', title: 'Projects' },
+  { id: 'data', title: 'Data' },
+  { id: 'system', title: 'System' },
+]);
+
+const GROUPS = Object.freeze([
+  { path: ['computer'], section: 'computers', title: 'Computer commands', usage: 'empty computer <command> [options]' },
+  { path: ['thing'], section: 'things', title: 'Thing commands', usage: 'empty thing <command> [options]' },
+  { path: ['project'], section: 'projects', title: 'Project commands', usage: 'empty project <command> [options]' },
+  { path: ['data'], section: 'data', title: 'Data commands', usage: 'empty data [command] [options]' },
+]);
+
+const HELP_FLAGS = new Set(['--help', '-h']);
+const CATALOG = Object.freeze(COMMANDS.map((entry) => Object.freeze(entry)));
+const BY_PATH = new Map(CATALOG.map((entry) => [entry.path.join(' '), entry]));
+const ROUTABLE = [...CATALOG]
+  .filter((entry) => entry.execution === 'remote');
+
+export function isRemoteCommand(argv) {
+  return ROUTABLE.some((entry) => {
+    if (!startsWithPath(argv, entry.path)) return false;
+    if (entry.routing === 'exact') return argv.length === entry.path.length;
+    if (entry.routing === 'json-only') {
+      return argv.slice(entry.path.length).every((argument) => argument === '--json');
+    }
+    return true;
+  });
+}
+
+export function remoteCommandPaths() {
+  return ROUTABLE.map((entry) => entry.path.join(' ')).sort();
+}
+
+export function commandInventory() {
+  return CATALOG.map((entry) => ({
+    command: entry.path.join(' '),
+    route: [...entry.path],
+    summary: entry.summary,
+    source: 'built-in',
+    location: entry.execution === 'local' ? 'client' : entry.execution === 'remote' ? 'resident' : 'hybrid',
+  }));
+}
+
+// The visible command table in section order, for generated documentation.
+export function commandReference() {
+  return SECTIONS.map((section) => ({
+    id: section.id,
+    title: section.title,
+    commands: CATALOG
+      .filter((entry) => entry.visible && entry.section === section.id)
+      .map((entry) => ({
+        command: entry.path.join(' '),
+        usage: entry.usage,
+        summary: entry.summary,
+        execution: entry.execution,
+        examples: [...entry.examples],
+        notes: [...entry.notes],
+      })),
+  }));
+}
+
+export function helpResponse(argv) {
+  const request = parseHelpRequest(argv);
+  if (!request) return null;
+  if (request.kind === 'top') return { code: 0, text: renderTopHelp(), error: null, top: true };
+
+  const key = request.path.join(' ');
+  const group = GROUPS.find((entry) => pathsEqual(entry.path, request.path));
+  const entry = BY_PATH.get(key);
+  if (group) return { code: 0, text: renderGroupHelp(group), error: null };
+  if (entry) return { code: 0, text: renderCommandHelp(entry), error: null };
+
+  const ancestor = [...GROUPS]
+    .sort((left, right) => right.path.length - left.path.length)
+    .find((candidate) => startsWithPath(request.path, candidate.path));
+  return {
+    code: 1,
+    text: ancestor ? renderGroupHelp(ancestor) : renderTopHelp(),
+    error: `Unknown help topic "${key}"`,
+  };
+}
+
+// Whether the first argv token belongs to a client-known command family.
+// Unknown families are candidate resident extension commands and are
+// resolved against the computer's inventory before forwarding.
+export function isKnownCommandFamily(token) {
+  return CATALOG.some((entry) => entry.path[0] === token) || GROUPS.some((group) => group.path[0] === token);
+}
+
+export function topHelpText() {
+  return renderTopHelp();
+}
+
+export function commandHelpText(pathText) {
+  const path = pathText.split(' ');
+  const group = GROUPS.find((entry) => pathsEqual(entry.path, path));
+  if (group) return renderGroupHelp(group);
+  const entry = BY_PATH.get(pathText);
+  return entry ? renderCommandHelp(entry) : null;
+}
+
+function command(pathText, usage, summary, section, execution, examples = [], visible = true, routing = 'prefix', notes = []) {
+  return { path: pathText.split(' '), usage, summary, section, execution, examples, visible, routing, notes };
+}
+
+function parseHelpRequest(argv) {
+  const args = argv.filter((argument) => argument !== '--json');
+  if (args[0] === 'help') {
+    const path = args.slice(1);
+    return path.length === 0 ? { kind: 'top' } : { kind: 'path', path };
+  }
+  if (args.length === 1 && HELP_FLAGS.has(args[0])) return { kind: 'top' };
+
+  const separator = args.indexOf('--');
+  const last = args.at(-1);
+  if (!HELP_FLAGS.has(last) || separator !== -1) return null;
+  const path = args.slice(0, -1);
+  if (path.length === 0) return { kind: 'top' };
+  if (BY_PATH.has(path.join(' ')) || GROUPS.some((entry) => pathsEqual(entry.path, path))) {
+    return { kind: 'path', path };
+  }
+
+  const leafPrefix = CATALOG.find((entry) => entry.path.length < path.length && startsWithPath(path, entry.path));
+  if (leafPrefix) return null;
+  return null;
+}
+
+function renderTopHelp() {
+  const lines = [
+    'EmptyOS external client',
+    '',
+    'Usage:',
+    '  empty [--computer <alias>] <command> [options]',
+  ];
+  for (const section of SECTIONS) {
+    const entries = CATALOG.filter((entry) => entry.visible && entry.section === section.id);
+    lines.push('', section.title, ...formatEntries(entries));
+  }
+  lines.push('', 'Run `empty <command> --help` for details.');
+  return `${lines.join('\n')}\n`;
+}
+
+function renderGroupHelp(group) {
+  const primary = BY_PATH.get(group.path.join(' '));
+  const entries = CATALOG.filter((entry) => entry.visible && entry.section === group.section && entry !== primary);
+  const lines = [
+    group.title,
+    '',
+    'Usage:',
+    `  ${primary ? `empty ${primary.usage}` : group.usage}`,
+  ];
+  if (primary) lines.push('', primary.summary);
+  lines.push(
+    '',
+    'Commands:',
+    ...formatEntries(entries),
+    '',
+    'Run `empty <command> --help` for details.',
+    '',
+  );
+  return lines.join('\n');
+}
+
+function renderCommandHelp(entry) {
+  const lines = [
+    'Usage:',
+    `  empty ${entry.usage}`,
+    '',
+    entry.summary,
+  ];
+  if (entry.notes.length > 0) lines.push('', ...entry.notes);
+  if (entry.examples.length > 0) lines.push('', 'Examples:', ...entry.examples.map((example) => `  ${example}`));
+  return `${lines.join('\n')}\n`;
+}
+
+function formatEntries(entries) {
+  const names = entries.map((entry) => entry.path.join(' '));
+  const width = Math.max(...names.map((name) => name.length));
+  return entries.map((entry, index) => `  ${names[index].padEnd(width)}  ${entry.summary}`);
+}
+
+function startsWithPath(argv, commandPath) {
+  return commandPath.every((part, index) => argv[index] === part);
+}
+
+function pathsEqual(left, right) {
+  return left.length === right.length && left.every((part, index) => right[index] === part);
+}

package/lib/config.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { ALIAS_PATTERN, SSH_TARGET_PATTERN } from './constants.js';
+import { ClientError } from './errors.js';
+
+const CONFIG_VERSION = 1;
+
+export function configPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(os.homedir(), '.config');
+  return path.join(base, 'emptyos', 'client.json');
+}
+
+export function emptyConfig() {
+  return { version: CONFIG_VERSION, defaultComputer: null, computers: {} };
+}
+
+export function readConfig(env = process.env) {
+  const file = configPath(env);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return emptyConfig();
+    throw new ClientError(`Cannot read client config at ${file}: ${error.message}`);
+  }
+
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new ClientError(`Invalid client config at ${file}: ${error.message}`);
+  }
+  validateConfig(value, file);
+  return value;
+}
+
+export function writeConfig(config, env = process.env) {
+  // TODO: serialize the client profile read-modify-write transaction across
+  // processes before external beta. Atomic replacement prevents torn files,
+  // but concurrent profile mutations can still overwrite one another.
+  const file = configPath(env);
+  validateConfig(config, file);
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dir, 0o700);
+
+  const temp = path.join(dir, `.${path.basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(temp, 'wx', 0o600);
+    fs.writeFileSync(fd, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temp, file);
+    fs.chmodSync(file, 0o600);
+  } 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 client config at ${file}: ${error.message}`);
+  }
+}
+
+export function validateAlias(alias) {
+  if (!ALIAS_PATTERN.test(alias ?? '')) {
+    throw new ClientError('Computer alias must contain only lowercase letters, digits, and single hyphens');
+  }
+  return alias;
+}
+
+export function validateTarget(target) {
+  if (!SSH_TARGET_PATTERN.test(target ?? '')) {
+    throw new ClientError('SSH host must be a hostname or user@hostname (use ~/.ssh/config for ports and options)');
+  }
+  return target;
+}
+
+export function validateReleaseCatalog(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ClientError('Platform release catalog must be an HTTPS URL');
+  }
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash) {
+    throw new ClientError('Platform release catalog must be an HTTPS URL without credentials or a fragment');
+  }
+  return url.href;
+}
+
+export function selectComputer(config, explicitAlias) {
+  const alias = explicitAlias ?? config.defaultComputer;
+  const source = explicitAlias ? 'explicit' : 'default';
+  if (!alias) {
+    throw new ClientError(
+      'No computer selected; run `empty connect <computer-url>` or select one with --computer <alias> or `empty computer use <alias>`',
+    );
+  }
+  const profile = config.computers[alias];
+  if (!profile) throw new ClientError(`Computer "${alias}" is not configured`);
+  return { alias, ...profile, source };
+}
+
+function validateConfig(value, file) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ClientError(`Invalid client config at ${file}: expected an object`);
+  }
+  if (value.version !== CONFIG_VERSION) {
+    throw new ClientError(`Unsupported client config version ${JSON.stringify(value.version)} at ${file}`);
+  }
+  if (!value.computers || typeof value.computers !== 'object' || Array.isArray(value.computers)) {
+    throw new ClientError(`Invalid client config at ${file}: computers must be an object`);
+  }
+  for (const [alias, profile] of Object.entries(value.computers)) {
+    validateAlias(alias);
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+      throw new ClientError(`Invalid profile for computer "${alias}" at ${file}`);
+    }
+    validateTarget(profile.target);
+    if (profile.releaseCatalog !== undefined) validateReleaseCatalog(profile.releaseCatalog);
+    validateTunnelProfile(profile, alias, file);
+  }
+  if (value.defaultComputer !== null && typeof value.defaultComputer !== 'string') {
+    throw new ClientError(`Invalid default computer at ${file}`);
+  }
+  if (value.defaultComputer !== null && !value.computers[value.defaultComputer]) {
+    throw new ClientError(`Default computer "${value.defaultComputer}" is not configured`);
+  }
+}
+
+function validateTunnelProfile(profile, alias, file) {
+  const fields = ['ownerOrigin', 'tunnelTokenPath', 'sshIdentityPath', 'sshKnownHostsPath'];
+  const present = fields.filter((field) => profile[field] !== undefined);
+  if (present.length === 0) return;
+  if (present.length !== fields.length) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${file}: ${fields.join(', ')} must be configured together`);
+  }
+
+  let origin;
+  try {
+    origin = new URL(profile.ownerOrigin);
+  } catch {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${file}: ownerOrigin must be an HTTPS origin`);
+  }
+  if (
+    origin.protocol !== 'https:'
+    || origin.username
+    || origin.password
+    || origin.pathname !== '/'
+    || origin.search
+    || origin.hash
+  ) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${file}: ownerOrigin must be an HTTPS origin`);
+  }
+
+  validateAbsoluteFile(profile.tunnelTokenPath, 'tunnelTokenPath', alias, file, { privateFile: true });
+  validateAbsoluteFile(profile.sshIdentityPath, 'sshIdentityPath', alias, file, { privateFile: true });
+  validateAbsoluteFile(profile.sshKnownHostsPath, 'sshKnownHostsPath', alias, file);
+}
+
+function validateAbsoluteFile(value, field, alias, configFile, { privateFile = false } = {}) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || value.includes('\0') || value.includes('\n') || value.includes('\r')) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: ${field} must be an absolute file path`);
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(value);
+  } catch (error) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: cannot inspect ${field}: ${error.message}`);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: ${field} must be a regular file, not a symbolic link`);
+  }
+  if (privateFile && (stat.mode & 0o777) !== 0o600) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: ${field} must have mode 0600`);
+  }
+  if (!privateFile && (stat.mode & 0o022) !== 0) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: ${field} must not be writable by group or other users`);
+  }
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new ClientError(`Invalid tunnel profile for computer "${alias}" at ${configFile}: ${field} must be owned by the current user`);
+  }
+}

package/lib/constants.js

@@ -0,0 +1,13 @@
+export const CLIENT_VERSION = '0.1.0';
+export const PROTOCOL_VERSION = 2;
+
+export const ALIAS_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const ID_PATTERN = /^[a-z0-9-]+$/;
+
+// Deliberately excludes SSH options, ports, paths, IPv6 literals, and shell
+// metacharacters. Users that need richer SSH setup can use ~/.ssh/config and
+// register its Host alias here.
+const USER = '[A-Za-z0-9_][A-Za-z0-9_.-]*';
+const HOST_LABEL = '[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?';
+const HOST = `${HOST_LABEL}(?:\\.${HOST_LABEL})*`;
+export const SSH_TARGET_PATTERN = new RegExp(`^(?:${USER}@)?${HOST}$`);

package/lib/errors.js

@@ -0,0 +1,16 @@
+export class ClientError extends Error {
+  constructor(message, code = 'client-error') {
+    super(message);
+    this.code = code;
+  }
+}
+
+// An argument/usage mistake: `command` is the catalog path ("computer add")
+// whose scoped help is appended to the error output; without one the
+// top-level client help is appended instead.
+export class UsageError extends ClientError {
+  constructor(message, command) {
+    super(message, 'usage');
+    this.command = command;
+  }
+}

package/lib/git.js

@@ -0,0 +1,28 @@
+import { runCaptured, runInherited } from './process.js';
+import { sshCommand, sshTransport } from './rpc.js';
+
+export function gitCaptured(args, { cwd, env = process.env, profile } = {}) {
+  return runCaptured(gitCommand(env), args, { cwd, env: gitEnvironment(profile, env) });
+}
+
+export function gitInherited(args, { cwd, env = process.env, profile } = {}) {
+  return runInherited(gitCommand(env), args, { cwd, env: gitEnvironment(profile, env) });
+}
+
+export function gitEnvironment(profile, env = process.env) {
+  if (!profile || typeof profile === 'string' || !profile.ownerOrigin) return env;
+  const transport = sshTransport(profile, env);
+  return {
+    ...env,
+    GIT_SSH_COMMAND: [sshCommand(env), ...transport.options].map(shellQuote).join(' '),
+    GIT_SSH_VARIANT: 'ssh',
+  };
+}
+
+function gitCommand(env) {
+  return env.EMPTYOS_GIT_COMMAND || 'git';
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}

package/lib/koans.js

@@ -0,0 +1,26 @@
+// The landing page's voice, rationed: a koan decorates the client's quiet
+// moments — an empty catalog, the top-level help — and only for a person at
+// a terminal. Pipes, --json, errors, and the resident CLI never carry one.
+export const KOANS = Object.freeze([
+  ['Nothing is missing.'],
+  ['Emptiness is infinite possibility, plus excellent storage.'],
+  ['Form is emptiness. Emptiness is a 2-core VM.'],
+  ['An empty room is not lacking. It is waiting.'],
+  ['A student asked the master: "What software should my computer come with?"', 'The master said nothing.'],
+  ['EmptyOS — nothing, as a service.'],
+  ['Nothing yet. Nothing wrong.'],
+].map(Object.freeze));
+
+// One koan per UTC day, so a session sees a steady line rather than a slot
+// machine. Returns the lines to splice after a message: a blank line, then
+// the koan indented like a hint. Empty when the output is not for a person.
+export function koanLines({ env = process.env, stdout = process.stdout, now = new Date() } = {}) {
+  if (env.EMPTYOS_PLAIN === '1' || !stdout.isTTY) return [];
+  const day = Math.floor(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()) / 86_400_000);
+  return ['', ...KOANS[day % KOANS.length].map((line) => `  ${line}`)];
+}
+
+export function withKoan(text, options) {
+  const lines = koanLines(options);
+  return lines.length === 0 ? text : `${text}${lines.join('\n')}\n`;
+}

package/lib/manifest.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { ClientError } from './errors.js';
+import { ID_PATTERN } from './constants.js';
+
+export function readThingId(root) {
+  const file = path.join(root, 'thing.yaml');
+  const raw = readManifestText(file);
+
+  const ids = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const match = /^(?:id|"id"|'id')\s*:\s*(?:([a-z0-9-]+)|"([a-z0-9-]+)"|'([a-z0-9-]+)')\s*(?:#.*)?$/.exec(line);
+    if (match) ids.push(match[1] ?? match[2] ?? match[3]);
+    else if (/^(?:id|"id"|'id')\s*:/.test(line)) {
+      throw new ClientError(`${file} must use a lowercase top-level id scalar`, 'invalid-manifest');
+    }
+  }
+  if (ids.length !== 1 || !ID_PATTERN.test(ids[0])) {
+    throw new ClientError(`${file} must contain exactly one top-level \`id: <thing-id>\``, 'invalid-manifest');
+  }
+  return ids[0];
+}
+
+export function readThingMetadata(root) {
+  const file = path.join(root, 'thing.yaml');
+  const text = readManifestText(file);
+  let raw;
+  try {
+    raw = YAML.parse(text);
+  } catch (error) {
+    throw new ClientError(`Cannot parse ${file}: ${error.message}`, 'invalid-manifest');
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ClientError(`${file} must be a YAML mapping`, 'invalid-manifest');
+  }
+  if (typeof raw.id !== 'string' || !ID_PATTERN.test(raw.id)) {
+    throw new ClientError(`${file} id is required and must match [a-z0-9-]+`, 'invalid-manifest');
+  }
+  if (typeof raw.name !== 'string' || raw.name.trim() === '') {
+    throw new ClientError(`${file} name is required`, 'invalid-manifest');
+  }
+  if (raw.type !== 'static' && raw.type !== 'service') {
+    throw new ClientError(`${file} type must be "static" or "service"`, 'invalid-manifest');
+  }
+  const visibility = raw.visibility ?? 'private';
+  if (visibility !== 'private' && visibility !== 'public') {
+    throw new ClientError(`${file} visibility must be "private" or "public"`, 'invalid-manifest');
+  }
+  const route = raw.route ?? `/${raw.id}`;
+  if (
+    typeof route !== 'string' || !route.startsWith('/') || route.length < 2 || route.endsWith('/') ||
+    route === '/api' || route.startsWith('/api/') || route === '/_system' || route.startsWith('/_system/')
+  ) {
+    throw new ClientError(`${file} has an invalid or reserved route`, 'invalid-manifest');
+  }
+  let project = null;
+  if (Object.hasOwn(raw, 'project')) {
+    if (typeof raw.project !== 'string' || !ID_PATTERN.test(raw.project)) {
+      throw new ClientError(`${file} project must match [a-z0-9-]+`, 'invalid-manifest');
+    }
+    project = raw.project;
+  }
+  if (Object.hasOwn(raw, 'data') && (
+    !Array.isArray(raw.data) ||
+    !raw.data.every((id) => typeof id === 'string' && ID_PATTERN.test(id)) ||
+    new Set(raw.data).size !== raw.data.length
+  )) {
+    throw new ClientError(`${file} data must be a list of unique Dataset ids matching [a-z0-9-]+`, 'invalid-manifest');
+  }
+  if (raw.type === 'static') validateStaticMetadata(root, file, raw);
+  else validateServiceMetadata(file, raw);
+  return { id: raw.id, name: raw.name, type: raw.type, visibility, project };
+}
+
+function validateStaticMetadata(root, file, raw) {
+  const directory = raw.directory ?? '.';
+  if (typeof directory !== 'string' || directory === '') {
+    throw new ClientError(`${file} directory must be a non-empty string`, 'invalid-manifest');
+  }
+  const resolved = path.resolve(root, directory);
+  if (!pathInside(root, resolved)) {
+    throw new ClientError(`${file} directory must resolve inside the Thing repository`, 'invalid-manifest');
+  }
+  if (!Object.hasOwn(raw, 'file')) return;
+  if (typeof raw.file !== 'string' || raw.file === '' || path.isAbsolute(raw.file) || /[\u0000-\u001f\u007f]/.test(raw.file)) {
+    throw new ClientError(`${file} file must be a non-empty safe relative path`, 'invalid-manifest');
+  }
+  const finalSegment = raw.file.split('/').at(-1);
+  const filePath = path.resolve(resolved, path.normalize(raw.file));
+  if (finalSegment === '' || finalSegment === '.' || finalSegment === '..' || filePath === resolved || !pathInside(resolved, filePath)) {
+    throw new ClientError(`${file} file must name a file inside the static directory`, 'invalid-manifest');
+  }
+}
+
+function validateServiceMetadata(file, raw) {
+  if (Object.hasOwn(raw, 'file')) throw new ClientError(`${file} file is only valid for a static Thing`, 'invalid-manifest');
+  if (typeof raw.command !== 'string' || raw.command.trim() === '' || /[\u0000-\u001f]/.test(raw.command)) {
+    throw new ClientError(`${file} service command is required and must not contain control characters`, 'invalid-manifest');
+  }
+  if (!Number.isInteger(raw.port) || raw.port < 1024 || raw.port > 65535) {
+    throw new ClientError(`${file} service port must be an integer from 1024 to 65535`, 'invalid-manifest');
+  }
+}
+
+function pathInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function readManifestText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    throw new ClientError(`Cannot read ${file}: ${error.message}`, 'invalid-manifest');
+  }
+}