@hasna/machines 0.0.23 → 0.0.25

package/README.md

@@ -57,15 +57,25 @@ should import `@hasna/machines/consumer`:
 ```ts
 import {
   MACHINES_CONSUMER_CONTRACT,
+  createMachineResolverSnapshot,
   discoverMachineTopology,
   getLocalMachineTopology,
   resolveMachineRoute,
+  resolveMachineWorkspace,
+  validateMachinesConsumerEnvelope,
 } from "@hasna/machines/consumer";
 
 console.log(MACHINES_CONSUMER_CONTRACT.schema_version);
 const topology = discoverMachineTopology();
 const local = getLocalMachineTopology();
 const route = resolveMachineRoute("spark01");
+const workspace = resolveMachineWorkspace({
+  machineId: "spark01",
+  projectId: "open-knowledge",
+  repoName: "open-knowledge",
+});
+const snapshot = createMachineResolverSnapshot({ route, workspace });
+console.log(validateMachinesConsumerEnvelope("resolver_snapshot", snapshot).ok);
 ```
 
 The SDK merges manifest entries, local heartbeats, SSH route hints, and
@@ -74,11 +84,19 @@ The SDK merges manifest entries, local heartbeats, SSH route hints, and
 when present, and fall back to local probes or app-local machine registries when
 it is absent.
 
-Topology, route, workspace, and compatibility JSON include `schema_version`,
-package version metadata, and capability flags. The current consumer contract
-version is `1`; the exported `MACHINES_CONSUMER_CONTRACT` records the stable
-entrypoint, envelope names, and stable exports used by downstream apps such as
-`@hasna/knowledge`.
+Topology, route, workspace, compatibility, and resolver-snapshot JSON include
+`schema_version`, package version metadata, capability flags, and cacheability
+metadata where downstream apps may persist resolver evidence. The current
+consumer contract version is `1`; the exported `MACHINES_CONSUMER_CONTRACT`
+records the stable entrypoint, envelope names, schema artifact, field
+capabilities, default resolver TTL, and stable exports used by downstream apps
+such as `@hasna/knowledge`.
+
+The package includes `schemas/machines-consumer.schema.json` and also exports
+`MACHINES_CONSUMER_SCHEMA_BUNDLE`, `getMachinesConsumerSchemaBundle()`, and
+`validateMachinesConsumerEnvelope()`. Downstream apps can use these helpers to
+validate route, workspace, compatibility, and resolver-snapshot envelopes
+without importing CLI, MCP, agent, installer, or storage-heavy internals.
 
 The package also ships a downstream conformance fixture for consumers that want
 to verify their optional adapter boundary without copying app-specific smoke
@@ -100,6 +118,32 @@ machines topology --no-tailscale --json
 machines route --machine spark01 --json
 ```
 
+## Screen sharing
+
+Open Screen Sharing (VNC) to any machine using its best live route — no stale
+IP bookmarks. The route resolver picks the current LAN address or Tailscale name
+automatically, so it keeps working even when DHCP rotates a machine's IP.
+
+```bash
+machines screen machine005                 # open Screen Sharing.app → vnc://<user>@<live-route>
+machines screen machine005 --print         # print the vnc:// URL instead of opening
+machines screen machine005 --json          # full resolution detail (route, confidence, user)
+machines screen --all                      # open every reachable machine
+machines screen --all --print              # list resolved vnc:// URLs for the whole fleet
+```
+
+Enable Remote Management / Screen Sharing on a fresh macOS machine over SSH
+(kickstart + SRP + legacy VNC password so user-password auth works from
+Screen Sharing.app and Apple Remote Desktop):
+
+```bash
+machines screen-enable --machine machine005 --user jo --vnc-password steaua17
+machines screen-enable --machine machine005 --user jo --print   # show the SSH command, don't run it
+```
+
+`--vnc-password` is truncated to 8 characters by the legacy VNC protocol. The
+user comes from the manifest (`metadata.user`) when present, or `--user`.
+
 Consumers that need repo paths can resolve trust-aware workspace mappings
 without importing the full machines app:
 

package/dist/agent/index.js

@@ -979,7 +979,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;