@emptyos/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishal Kapur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# EmptyOS external client
+
+This package is the workstation-side `empty` command, published to npm as
+`@emptyos/client`. Run every `empty` command in the local terminal: the client
+either handles it locally or transports it to the selected EmptyOS computer.
+It requires Node.js 20 or newer.
+
+Installing the client, connecting to a computer, putting files on it, sharing,
+and publishing are described at https://emptyos.com/docs/. This README keeps
+the contracts behind those pages: profile format, transport, publish
+mechanics, and development notes.
+
+The companion agent skill is at `skills/emptyos-computer/` and ships in the
+package. `empty skill install` copies it to `~/.agents/skills/emptyos-computer/`;
+`--dir <path>` chooses another skills directory, and a re-run replaces the
+earlier copy. It is a small bootstrap into this client and the resident
+`~/EMPTY.md` contract.
+
+For checkout development, the repository root provides a managed local
+computer and isolated client profile. Run `npm run dev` at the root, then use
+`npm run empty -- <command>` in another terminal. This exercises the same
+structured request and Git transport boundaries without linking the client or
+editing your real profiles; see the root [`README.md`](../README.md#local-development)
+for setup, persistence, testing, and limitations.
+
+## Computer profiles
+
+Registering a computer makes one noninteractive RPC call to confirm that the
+computer speaks protocol version 2. It does not make the new profile the
+default automatically.
+
+```sh
+empty computer add personal \
+  --host owner@personal.example
+empty computer use personal
+empty computers
+empty computer show --json
+empty computer remove personal
+```
+
+`empty connect <computer-url>` pairs with an EmptyOS-managed computer without
+an exe.dev account; the walkthrough is at https://emptyos.com/docs/start/. On
+approval the client stores a new Ed25519 identity, tunnel token, and pinned
+host key under its private config directory. Pairing secrets and tunnel token
+contents are never placed in URLs, process arguments, or logs. `connect`
+selects the new profile when no default computer exists; otherwise the
+existing default remains unchanged.
+
+Use an SSH config `Host` name when a connection needs a port, proxy, key, or
+other SSH option. Stored targets intentionally accept only a hostname or
+`user@hostname` so they cannot inject SSH options or remote shell text.
+
+An EmptyOS-managed tunnel profile can use the same version 1 config format
+without requiring an exe.dev account for the person using the client. Its
+four tunnel fields are all required together:
+
+```json
+{
+  "target": "exedev@computer.example",
+  "ownerOrigin": "https://computer.example",
+  "tunnelTokenPath": "/Users/me/.config/emptyos/computer.token",
+  "sshIdentityPath": "/Users/me/.ssh/emptyos_computer",
+  "sshKnownHostsPath": "/Users/me/.ssh/emptyos_known_hosts"
+}
+```
+
+`ownerOrigin` must be a credential-free HTTPS origin. All three configured
+files must be regular files owned by the current user and use absolute paths.
+The token and private key must have mode `0600`; the known-hosts file must not
+be group- or other-writable. The client reads the bearer token only
+inside its SSH proxy helper. Token contents never appear in process arguments,
+URLs, profile output, or logs. Tunnel SSH ignores user SSH configuration,
+uses only the configured identity, and requires the pinned known-hosts entry.
+Existing profiles containing only `target` continue to use direct SSH.
+
+Profiles live at `$XDG_CONFIG_HOME/emptyos/client.json`, or at
+`~/.config/emptyos/client.json` when `XDG_CONFIG_HOME` is unset. The directory
+is mode `0700` and the atomically replaced file is mode `0600`.
+
+`--release-catalog` is optional. It replaces the official HTTPS catalog used
+by `empty computer update` for that profile. Every profile can also update
+from an explicitly supplied catalog or local release artifact.
+
+`--computer <alias>` overrides the default for a command that operates on a
+computer:
+
+```sh
+empty --computer work things --json
+```
+
+It is rejected for `connect` and the local profile-registry commands
+`computers`, `computer add`, `computer use`, and `computer remove`, where an
+override would otherwise be silently ignored.
+
+## Commands and help
+
+`empty --help` is the complete command inventory. Help is resolved locally, so
+it works without a selected computer or SSH connection:
+
+```sh
+empty --help
+empty thing --help
+empty put --help
+empty help data describe
+```
+
+The client handles computer profiles, help, and version output locally. `put`,
+`clone`, platform updates, and `ssh` combine local state with Git or SSH.
+A route outside the client's command families is checked against the
+computer's command inventory: a registered resident owner command is forwarded
+as structured argv so it works without a client release, while anything else
+fails locally with client usage. `empty commands` merges both command
+inventories.
+
+Human catalog commands use the selected computer alias in useful empty states:
+
+```text
+Computer personal is empty — no Things yet
+
+Put its first Thing:
+  empty put <path> [--as <id>]
+  empty put <path> [--as <id>] [--name <name>] [--project <project-id>] [--public]
+```
+
+The client checks emptiness through the existing JSON form. Non-empty tables
+remain resident-rendered and pass through unchanged. Explicit `--json` output
+preserves valid resident results; workstation, Git, transport, and resident
+failures return one JSON object with a stable `code` and human-readable
+`error`. `thing add <path>` remains unavailable from a workstation because its
+argument would be a path on the computer; its help explains the supported
+`put` workflow.
+
+Forwarded commands use one fixed SSH remote command with a base64url-encoded
+JSON request. A Thing import uses a separate fixed endpoint for the same
+structured metadata and streams a Git bundle on stdin, so file bytes never
+enter the bounded argv payload. SSH runs with `BatchMode=yes`, a ten-second
+connection timeout, and no TTY. Human-mode remote output passes through;
+structured commands preserve valid resident JSON and normalize local or
+transport failures at the client error boundary. When SSH itself fails (exit
+255), the tunnel helper first explains why the computer is unreachable, such
+as an address that no longer resolves, and the client ends with a hint naming
+the computer profile.
+
+Before an assigned create or `put`, the client reads the resident version
+response. Generated starter assignment requires `thingCreateProject`; `put`
+requires the type-neutral `thingImport` capability. The client and computer use
+protocol 2; unsupported forms stop before staging or upload with an explicit
+`empty computer update` remediation.
+
+`empty ssh` without arguments opens the ordinary owner SSH session. Arguments
+after `--` are an explicit raw remote command and consequently have the normal
+remote-shell semantics of `ssh host command...`; use transported `empty`
+commands for structured, injection-resistant RPC.
+
+## Koans
+
+At a terminal, the client's quiet moments end with one of the landing page's
+koans: `empty computers` with no profiles, `empty things` / `projects` /
+`data` / `changes` on a computer that has none yet, and the top-level help.
+The koan rotates daily. Piped output, `--json`, errors, command help, and the
+resident CLI never carry one; set `EMPTYOS_PLAIN=1` to turn them off entirely.
+
+## Platform updates
+
+Check the selected computer without changing it, then apply the configured
+release when the plan is acceptable:
+
+```sh
+empty computer update --check
+empty computer update
+```
+
+`--computer <alias>` selects a different profile for either command. `--json`
+returns the selected computer, release and artifact identifiers, status,
+per-path plan, warnings, updater output, and exit status without decorating
+them.
+
+If apply reports `needs-reconciliation`, the structured result also includes a
+retained stage and exact next command. Continue from an agent: inspect the
+stage's `RECONCILE.md` and detached candidate through `empty ssh`, merge only
+the declared conflicting paths, run the candidate tests, then resume the same
+transaction:
+
+```sh
+empty computer update --resume <stage-name>
+```
+
+Resume does not fetch a newer release. It reuses the retained target and
+rejects stale live state, edits outside the conflict set, or failed validators.
+
+The default source is the official catalog at
+`https://release.emptyos.com/platform/v1/catalog.json`. A profile-level
+`--release-catalog` replaces it for that computer. Supply `--catalog` to
+override either catalog for one invocation, or use an immutable artifact that
+was obtained through a trusted operator channel:
+
+```sh
+empty computer update --catalog https://releases.example/emptyos/catalog.json
+empty --computer work computer update --release ./emptyos-platform-release.json
+```
+
+The client validates HTTPS on every catalog redirect, bounds downloads,
+verifies the catalog's artifact SHA-256, and validates the canonical artifact
+and every embedded file before staging it. These checks detect corruption and
+catalog/artifact mismatch; they are not a publisher signature. Trust comes
+from the official HTTPS authority, a profile or invocation catalog selected by
+the operator, or the trusted channel used to obtain a local artifact.
+
+## Publish contract
+
+`put`, `clone`, and `put .` are described at https://emptyos.com/docs/publish/.
+This section keeps the mechanics behind them.
+
+`put` snapshots the selected content as one parentless commit without source
+history, remotes, hooks, or Git configuration, and streams it as a Git bundle
+on stdin to a fixed import endpoint. Upload happens before the resident
+mutation lock; installation is revalidated and atomic, and a failed validation
+leaves no partial Thing behind. Successful initial `--json` output reports the
+detected `sourceKind`, content counts, installed head and manifest facts,
+generated `scaffolding`, `preparation`, `verification`, `installation`, and
+service registration state.
+
+`clone` first confirms the Thing exists, clones `<ssh-target>:things/<id>`,
+validates the top-level `id` in `thing.yaml`, and stores three clone-local Git
+keys:
+
+- `emptyos.computer`
+- `emptyos.profileTarget`
+- `emptyos.target` (`thing://<id>`)
+
+The profile target snapshot prevents an alias that was later retargeted from
+silently publishing a checkout to another computer. Clone JSON reports the
+local root plus the computer, immutable profile target, and `thing://<id>`
+binding.
+
+Publish never rewrites local history. It requires:
+
+- a bound repository on an attached branch;
+- a matching profile target and `thing.yaml` ID;
+- no tracked or untracked worktree changes;
+- a regular, executable, non-symlink `./verify` that succeeds locally; and
+- exactly one non-merge commit on top of the current origin default-branch
+  HEAD.
+
+After fetching and validating the live head, publish pushes `HEAD` to
+`refs/emptyos/candidates/<full-sha>` and requests:
+
+```text
+thing activate <id> --sha <sha> --expected-base <live-head> [--json]
+```
+
+The activation response and exit status are passed through to the caller.
+
+## Development
+
+```sh
+cd client
+npm install
+npm link      # optional: run this checkout as `empty`
+npm test
+```
+
+Tests use temporary real Git repositories and fake `ssh`/`git` executables;
+they do not require a network connection or an EmptyOS computer.

package/bin/empty.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/lib/browser.js

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+
+// Best effort: hand the URL to the platform's default handler and report
+// whether that opener started. Callers keep the URL printed for the manual path.
+export function openInBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
+  const [command, args] = platform === 'darwin' ? ['open', [url]]
+    : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.once('error', () => resolve(false));
+    child.once('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}

package/lib/catalog-output.js

@@ -0,0 +1,73 @@
+const SPECS = Object.freeze({
+  things: {
+    empty(value) {
+      return Array.isArray(value) && value.length === 0;
+    },
+    message(alias, koan = []) {
+      return [
+        `Computer ${alias} is empty — no Things yet`,
+        ...koan,
+        '',
+        'Put its first Thing:',
+        '  empty put <path> [--as <id>]',
+        '',
+      ].join('\n');
+    },
+  },
+  projects: {
+    empty(value) {
+      return Array.isArray(value) && value.length === 0;
+    },
+    message(alias, koan = []) {
+      return [
+        `Computer ${alias} has no Projects yet`,
+        ...koan,
+        '',
+        'Create one:',
+        '  empty project create <id> <name>',
+        '',
+      ].join('\n');
+    },
+  },
+  data: {
+    empty(value) {
+      return Array.isArray(value) && value.length === 0;
+    },
+    message(alias, koan = []) {
+      return [
+        `Computer ${alias} has no Datasets yet`,
+        ...koan,
+        '',
+        'Use `empty ssh` for resident Data work; SQLite files stay on the computer',
+        '',
+      ].join('\n');
+    },
+  },
+  changes: {
+    empty(value) {
+      return value && typeof value === 'object' && Array.isArray(value.changes) && value.changes.length === 0;
+    },
+    message(alias, koan = []) {
+      return [`Computer ${alias} has no committed changes yet`, ...koan, ''].join('\n');
+    },
+    humanEmptyOutput: 'No committed changes\n',
+  },
+});
+
+export function humanCatalogSpec(argv) {
+  if (argv.length !== 1) return null;
+  return SPECS[argv[0]] ? { command: argv[0], ...SPECS[argv[0]] } : null;
+}
+
+export function parseCatalogJson(command, stdout) {
+  let value;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  const valid = command === 'changes'
+    ? value && typeof value === 'object' && Array.isArray(value.changes)
+    : Array.isArray(value);
+  return valid ? value : null;
+}