@hasna/machines 0.0.23 → 0.0.25

package/dist/cli/index.js

@@ -993,7 +993,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -2601,6 +2601,9 @@ var {
   Help
 } = import__.default;
 
+// src/cli/index.ts
+import { execFileSync } from "child_process";
+
 // node_modules/chalk/source/vendor/ansi-styles/index.js
 var ANSI_BACKGROUND_OFFSET = 10;
 var wrapAnsi16 = (offset = 0) => (code) => `\x1B[${code + offset}m`;
@@ -7165,6 +7168,7 @@ function writeManifest(manifest, path = getManifestPath()) {
     generatedAt: new Date().toISOString(),
     machines: normalizeMachines(manifest.machines)
   };
+  fleetSchema.parse(payload);
   writeFileSync(path, `${JSON.stringify(payload, null, 2)}
 `, "utf8");
   return path;
@@ -7200,9 +7204,10 @@ function manifestList() {
   return readManifest();
 }
 function manifestAdd(machine) {
+  const validatedMachine = machineSchema.parse(machine);
   const manifest = readManifest();
-  const nextMachines = manifest.machines.filter((entry) => entry.id !== machine.id);
-  nextMachines.push(machine);
+  const nextMachines = manifest.machines.filter((entry) => entry.id !== validatedMachine.id);
+  nextMachines.push(validatedMachine);
   const nextManifest = { ...manifest, machines: nextMachines };
   writeManifest(nextManifest);
   return nextManifest;
@@ -7227,6 +7232,7 @@ function manifestValidate() {
 }
 
 // src/commands/setup.ts
+import { homedir as homedir2 } from "os";
 init_db();
 function quote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -7275,11 +7281,11 @@ function buildPackageSteps(machine) {
     const manager = pkg.manager || (machine.platform === "macos" ? "brew" : "apt");
     let command = pkg.name;
     if (manager === "bun") {
-      command = `bun install -g ${pkg.name}`;
+      command = `bun install -g ${quote(pkg.name)}`;
     } else if (manager === "brew") {
-      command = `brew install ${pkg.name}`;
+      command = `brew install ${quote(pkg.name)}`;
     } else if (manager === "apt") {
-      command = `sudo apt-get install -y ${pkg.name}`;
+      command = `sudo apt-get install -y ${quote(pkg.name)}`;
     }
     return {
       id: `package-${index + 1}`,
@@ -7297,7 +7303,7 @@ function buildSetupPlan(machineId) {
   const target = selected || {
     id: currentMachineId,
     platform: "linux",
-    workspacePath: "~/workspace"
+    workspacePath: `${homedir2()}/workspace`
   };
   const steps = [...buildBaseSteps(target), ...buildPackageSteps(target)];
   return {
@@ -7343,7 +7349,7 @@ function runSetup(machineId, options = {}) {
 }
 
 // src/commands/backup.ts
-import { homedir as homedir2 } from "os";
+import { homedir as homedir3, hostname as hostname3 } from "os";
 import { join as join3 } from "path";
 var MACHINES_BACKUP_BUCKET_ENV = "HASNA_MACHINES_S3_BUCKET";
 var MACHINES_BACKUP_BUCKET_FALLBACK_ENV = "MACHINES_S3_BUCKET";
@@ -7392,7 +7398,7 @@ function resolveBackupTarget(options = {}) {
   };
 }
 function defaultBackupSources() {
-  const home = homedir2();
+  const home = homedir3();
   return [
     join3(home, ".hasna"),
     join3(home, ".ssh"),
@@ -7401,7 +7407,7 @@ function defaultBackupSources() {
 }
 function buildBackupPlan(bucket, prefix) {
   const target = resolveBackupTarget({ bucket, prefix });
-  const archivePath = join3(homedir2(), ".hasna", "machines", "backup.tgz");
+  const archivePath = join3(homedir3(), ".hasna", "machines", "backup.tgz");
   const sources = defaultBackupSources();
   const steps = [
     {
@@ -7413,7 +7419,7 @@ function buildBackupPlan(bucket, prefix) {
     {
       id: "backup-upload",
       title: "Upload archive to S3",
-      command: `aws s3 cp ${quote2(archivePath)} s3://${target.bucket}/${target.prefix}/$(hostname)-backup.tgz`,
+      command: `aws s3 cp ${quote2(archivePath)} ${quote2(`s3://${target.bucket}/${target.prefix}/${hostname3()}-backup.tgz`)}`,
       manager: "custom"
     }
   ];
@@ -7452,13 +7458,13 @@ function runBackup(bucket, prefix, options = {}) {
 }
 
 // src/commands/cert.ts
-import { homedir as homedir3, platform as platform2 } from "os";
+import { homedir as homedir4, platform as platform2 } from "os";
 import { join as join4 } from "path";
 function quote3(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function certDir() {
-  return join4(homedir3(), ".hasna", "machines", "certs");
+  return join4(homedir4(), ".hasna", "machines", "certs");
 }
 function buildCertPlan(domains) {
   if (domains.length === 0) {
@@ -7618,23 +7624,28 @@ function diffMachines(leftMachineId, rightMachineId) {
 // src/remote.ts
 init_db();
 import { spawnSync as spawnSync2 } from "child_process";
-import { hostname as hostname4 } from "os";
+import { hostname as hostname5 } from "os";
 
 // src/topology.ts
 init_db();
 import { existsSync as existsSync5 } from "fs";
-import { arch as arch2, hostname as hostname3, platform as platform3, userInfo as userInfo2 } from "os";
+import { arch as arch2, hostname as hostname4, platform as platform3, userInfo as userInfo2 } from "os";
 import { spawnSync } from "child_process";
 init_paths();
 var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
 var MACHINES_PACKAGE_NAME = "@hasna/machines";
+var DEFAULT_MACHINE_RESOLVER_TTL_MS = 24 * 60 * 60 * 1000;
 var MACHINES_CONSUMER_CAPABILITIES = {
   topology: true,
   compatibility: true,
   route_resolution: true,
   cli_json_fallback: true,
   workspace_path_mapping: true,
-  workspace_diagnostics: true
+  workspace_diagnostics: true,
+  schema_artifacts: true,
+  cacheability_metadata: true,
+  resolver_snapshots: true,
+  field_capability_descriptors: true
 };
 function getMachinesConsumerCapabilities() {
   return { ...MACHINES_CONSUMER_CAPABILITIES };
@@ -7842,7 +7853,7 @@ function discoverMachineTopology(options = {}) {
     capabilities: getMachinesConsumerCapabilities(),
     generated_at: now.toISOString(),
     local_machine_id: localMachineId,
-    local_hostname: hostname3(),
+    local_hostname: hostname4(),
     current_platform: normalizePlatform2(),
     manifest_path_known: existsSync5(getManifestPath()),
     machines,
@@ -7867,7 +7878,7 @@ function routeTargetMatches(machine, requested) {
 }
 function findRouteMachine(topology, requestedMachineId) {
   const requested = normalizeMachineAlias(requestedMachineId);
-  if (requested === "local" || requested === "localhost" || requested === normalizeMachineAlias(hostname3()) || requested === normalizeMachineAlias(topology.local_machine_id)) {
+  if (requested === "local" || requested === "localhost" || requested === normalizeMachineAlias(hostname4()) || requested === normalizeMachineAlias(topology.local_machine_id)) {
     return {
       machine: topology.machines.find((machine) => machine.machine_id === topology.local_machine_id) ?? null,
       matchedBy: "local_alias"
@@ -7905,11 +7916,69 @@ function routeConfidence(input) {
     return "low";
   return "none";
 }
+function addMilliseconds(date, milliseconds) {
+  return new Date(date.getTime() + milliseconds).toISOString();
+}
+function routeAuthority(input) {
+  if (!input.machine)
+    return "unresolved";
+  if (input.matchedBy === "fallback")
+    return "fallback";
+  if (input.selectedHint?.kind === "local")
+    return "live_topology";
+  if (input.selectedHint?.kind === "tailscale" || input.machine.tailscale.online !== null)
+    return "live_topology";
+  if (input.machine.manifest_declared)
+    return "manifest";
+  return "open-machines";
+}
+function workspaceAuthority(paths) {
+  const sources = [paths.workspace_root.source, paths.project_root.source, paths.open_files_root.source];
+  if (sources.some((source) => source === "argument"))
+    return "argument";
+  if (sources.some((source) => source === "manifest_metadata"))
+    return "manifest_metadata";
+  if (sources.some((source) => source === "manifest"))
+    return "manifest";
+  if (sources.some((source) => source === "inferred"))
+    return "inferred";
+  if (sources.every((source) => source === "unresolved"))
+    return "unresolved";
+  return "open-machines";
+}
+function cacheability(input) {
+  const ttlMs = input.ttlMs === undefined ? DEFAULT_MACHINE_RESOLVER_TTL_MS : input.ttlMs;
+  const expiresAt = typeof ttlMs === "number" && ttlMs > 0 ? addMilliseconds(input.observedAt, ttlMs) : null;
+  const stale = expiresAt ? input.now.getTime() > new Date(expiresAt).getTime() : false;
+  const confidenceCacheable = input.confidence !== "none" && input.confidence !== "low";
+  const cacheable = input.ok && confidenceCacheable && !stale && input.authority !== "unresolved";
+  const reasons = [...input.reasons];
+  if (!input.ok)
+    reasons.push("resolver_not_ok");
+  if (!confidenceCacheable)
+    reasons.push(`low_confidence:${input.confidence}`);
+  if (stale)
+    reasons.push("stale");
+  if (input.authority === "unresolved")
+    reasons.push("unresolved_authority");
+  return {
+    observed_at: input.observedAt.toISOString(),
+    verified_at: input.ok ? input.now.toISOString() : null,
+    expires_at: expiresAt,
+    ttl_ms: typeof ttlMs === "number" && ttlMs > 0 ? ttlMs : null,
+    source_authority: input.authority,
+    confidence: input.confidence,
+    cacheable,
+    stale,
+    reasons: [...new Set(reasons)].sort()
+  };
+}
 function resolveMachineRoute(machineId, options = {}) {
+  const now = options.now ?? new Date;
   const topology = options.topology ?? discoverMachineTopology(options);
   const warnings = [...topology.warnings];
   const { machine, matchedBy } = findRouteMachine(topology, machineId);
-  const generatedAt = (options.now ?? new Date).toISOString();
+  const generatedAt = now.toISOString();
   if (!machine) {
     warnings.push(`machine_not_found:${machineId}`);
     return {
@@ -7933,16 +8002,27 @@ function resolveMachineRoute(machineId, options = {}) {
         tailscale_online: null,
         selected_hint: null
       },
+      cacheability: cacheability({
+        ok: false,
+        observedAt: now,
+        now,
+        ttlMs: options.resolverTtlMs,
+        authority: "unresolved",
+        confidence: "none",
+        reasons: [`machine_not_found:${machineId}`]
+      }),
       warnings
     };
   }
   const selectedHint = selectRouteHint(machine.route_hints);
   const route = selectedHint?.kind ?? machine.ssh.route ?? "unknown";
   const local = route === "local" || machine.machine_id === topology.local_machine_id;
+  const confidence = routeConfidence({ machine, hint: selectedHint, matchedBy });
+  const ok = Boolean(selectedHint?.target);
   return {
     schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
     package: topology.package,
-    ok: Boolean(selectedHint?.target),
+    ok,
     machine_id: machine.machine_id,
     requested_machine_id: machineId,
     generated_at: generatedAt,
@@ -7950,7 +8030,7 @@ function resolveMachineRoute(machineId, options = {}) {
     source: route,
     target: selectedHint?.target ?? null,
     command_target: selectedHint?.target ?? null,
-    confidence: routeConfidence({ machine, hint: selectedHint, matchedBy }),
+    confidence,
     local,
     evidence: {
       topology: true,
@@ -7960,6 +8040,15 @@ function resolveMachineRoute(machineId, options = {}) {
       tailscale_online: machine.tailscale.online,
       selected_hint: selectedHint
     },
+    cacheability: cacheability({
+      ok,
+      observedAt: now,
+      now,
+      ttlMs: options.resolverTtlMs,
+      authority: routeAuthority({ machine, selectedHint, matchedBy }),
+      confidence,
+      reasons: selectedHint ? [] : ["route_target_unresolved"]
+    }),
     warnings
   };
 }
@@ -8256,10 +8345,11 @@ function metadataKeysForDiagnostics(metadata) {
   return Object.keys(metadata).filter((key) => !/(secret|token|key|password|credential)/i.test(key)).sort();
 }
 function resolveMachineWorkspace(options) {
+  const now = options.now ?? new Date;
   const topology = options.topology ?? discoverMachineTopology(options);
   const warnings = [...topology.warnings];
   const { machine, matchedBy } = findRouteMachine(topology, options.machineId);
-  const generatedAt = (options.now ?? new Date).toISOString();
+  const generatedAt = now.toISOString();
   const repoName = options.repoName ?? options.projectId;
   const openFilesRepoName = options.openFilesRepoName ?? "open-files";
   if (!machine) {
@@ -8286,6 +8376,15 @@ function resolveMachineWorkspace(options) {
         manifest_declared: null,
         metadata_keys: []
       },
+      cacheability: cacheability({
+        ok: false,
+        observedAt: now,
+        now,
+        ttlMs: options.resolverTtlMs,
+        authority: "unresolved",
+        confidence: "none",
+        reasons: [`machine_not_found:${options.machineId}`]
+      }),
       warnings
     };
     const diagnostics2 = workspaceDiagnostics({
@@ -8317,10 +8416,16 @@ function resolveMachineWorkspace(options) {
     warnings.push(`open_files_root_inferred:${options.projectId}`);
   if (!projectRootPath)
     warnings.push(`project_root_unresolved:${options.projectId}`);
+  const workspacePaths = {
+    workspace_root: { path: workspaceRootPath, source: workspaceRootSource },
+    project_root: { path: projectRootPath, source: projectRootSource },
+    open_files_root: { path: openFilesRootPath, source: openFilesRootSource }
+  };
+  const workspaceOk = Boolean(projectRootPath);
   const resolution = {
     schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
     package: topology.package,
-    ok: Boolean(projectRootPath),
+    ok: workspaceOk,
     requested_machine_id: options.machineId,
     machine_id: machine.machine_id,
     generated_at: generatedAt,
@@ -8335,11 +8440,7 @@ function resolveMachineWorkspace(options) {
       trust_status: trustStatus(machine),
       auth_status: authStatus(machine)
     },
-    paths: {
-      workspace_root: { path: workspaceRootPath, source: workspaceRootSource },
-      project_root: { path: projectRootPath, source: projectRootSource },
-      open_files_root: { path: openFilesRootPath, source: openFilesRootSource }
-    },
+    paths: workspacePaths,
     diagnostics: [],
     repair_hints: [],
     evidence: {
@@ -8348,6 +8449,15 @@ function resolveMachineWorkspace(options) {
       manifest_declared: machine.manifest_declared,
       metadata_keys: metadataKeysForDiagnostics(metadata)
     },
+    cacheability: cacheability({
+      ok: workspaceOk,
+      observedAt: now,
+      now,
+      ttlMs: options.resolverTtlMs,
+      authority: workspaceAuthority(workspacePaths),
+      confidence: workspaceOk ? "medium" : "none",
+      reasons: projectRootPath ? [] : [`project_root_unresolved:${options.projectId}`]
+    }),
     warnings
   };
   const diagnostics = workspaceDiagnostics({
@@ -8393,7 +8503,7 @@ function shellQuote3(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function machineIsLocal(machineId, localMachineId) {
-  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname4();
+  return machineId === "local" || machineId === "localhost" || machineId === localMachineId || machineId === hostname5();
 }
 function resolveMachineCommand(machineId, command, localMachineId = getLocalMachineId()) {
   if (machineIsLocal(machineId, localMachineId)) {
@@ -8445,20 +8555,21 @@ function shellQuote4(value) {
 }
 function buildAppCommand(machine, app) {
   const packageName = getPackageName(app);
+  const quotedPackageName = shellQuote4(packageName);
   const manager = getAppManager(machine, app);
   if (manager === "custom") {
     return packageName;
   }
   if (machine.platform === "macos") {
     if (manager === "cask") {
-      return `brew install --cask ${packageName}`;
+      return `brew install --cask ${quotedPackageName}`;
     }
-    return `brew install ${packageName}`;
+    return `brew install ${quotedPackageName}`;
   }
   if (machine.platform === "windows") {
-    return `winget install ${packageName}`;
+    return `winget install ${quotedPackageName}`;
   }
-  return `sudo apt-get install -y ${packageName}`;
+  return `sudo apt-get install -y ${quotedPackageName}`;
 }
 function buildAppProbeCommand(machine, app) {
   const packageName = shellQuote4(getPackageName(app));
@@ -9041,8 +9152,55 @@ function listPorts(machineId) {
   };
 }
 
+// src/commands/screen.ts
+function shellQuote6(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function splitTarget(target) {
+  const at = target.indexOf("@");
+  if (at === -1)
+    return [null, target];
+  return [target.slice(0, at), target.slice(at + 1)];
+}
+function resolveScreenTarget(machineId, options = {}) {
+  const resolved = resolveMachineRoute(machineId, options);
+  if (!resolved.ok || !resolved.target) {
+    throw new Error(`Machine route not found: ${machineId}`);
+  }
+  if (resolved.route === "unknown") {
+    throw new Error(`Machine route is not reachable for screen sharing: ${machineId}`);
+  }
+  let [user, host] = splitTarget(resolved.target);
+  if (!user) {
+    const topology = options.topology ?? discoverMachineTopology(options);
+    const entry = topology.machines.find((m) => m.machine_id === (resolved.machine_id ?? machineId));
+    user = entry?.user ?? null;
+  }
+  const url = user ? `vnc://${user}@${host}` : `vnc://${host}`;
+  return {
+    machineId: resolved.machine_id ?? machineId,
+    user,
+    host,
+    url,
+    route: resolved.route,
+    confidence: resolved.confidence,
+    warnings: resolved.warnings
+  };
+}
+function buildScreenEnableRemoteCommand(user, vncPassword) {
+  const kickstart = "/System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart";
+  const lines = [
+    `dseditgroup -o edit -a ${shellQuote6(user)} -t user com.apple.access_screensharing 2>/dev/null || true`,
+    "defaults write /Library/Preferences/com.apple.RemoteManagement AllowSRPForNetworkNodes -bool true",
+    `${kickstart} -configure -clientopts -setvnclegacy -vnclegacy yes -setvncpw -vncpw ${shellQuote6(vncPassword)}`,
+    `${kickstart} -activate -configure -access -on -users ${shellQuote6(user)} -privs -all -restart -agent -menu`
+  ];
+  return lines.join(" && ");
+}
+
 // src/commands/sync.ts
 import { existsSync as existsSync7, lstatSync, readFileSync as readFileSync5, symlinkSync, copyFileSync } from "fs";
+import { homedir as homedir5 } from "os";
 init_paths();
 init_db();
 function quote4(value) {
@@ -9062,13 +9220,13 @@ function packageCheckCommand(machine, packageName, manager = machine.platform ==
 }
 function packageInstallCommand(machine, packageName, manager = machine.platform === "macos" ? "brew" : "apt") {
   if (manager === "bun") {
-    return `bun install -g ${packageName}`;
+    return `bun install -g ${quote4(packageName)}`;
   }
   if (manager === "brew") {
-    return `brew install ${packageName}`;
+    return `brew install ${quote4(packageName)}`;
   }
   if (manager === "apt") {
-    return `sudo apt-get install -y ${packageName}`;
+    return `sudo apt-get install -y ${quote4(packageName)}`;
   }
   return packageName;
 }
@@ -9121,7 +9279,7 @@ function buildSyncPlan(machineId) {
   const target = selected || {
     id: currentMachineId,
     platform: "linux",
-    workspacePath: "~/workspace"
+    workspacePath: `${homedir5()}/workspace`
   };
   const actions = [
     ...detectPackageActions(target),
@@ -9388,7 +9546,7 @@ var DEFAULT_COMMANDS = [
 function defaultPackages() {
   return [{ name: "@hasna/machines", command: "machines", expectedVersion: getPackageVersion(), required: true }];
 }
-function shellQuote6(value) {
+function shellQuote7(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 function commandId(value) {
@@ -9439,7 +9597,7 @@ function defaultRunner2(machineId, command) {
   return runMachineCommand(machineId, command);
 }
 function inspectCommand(machineId, spec, runner) {
-  const command = shellQuote6(spec.command);
+  const command = shellQuote7(spec.command);
   const versionArgs = spec.versionArgs ?? "--version";
   const script = [
     `cmd=${command}`,
@@ -9468,7 +9626,7 @@ function fieldCommand(field) {
 }
 function inspectWorkspace(machineId, spec, runner) {
   const script = [
-    `path=${shellQuote6(spec.path)}`,
+    `path=${shellQuote7(spec.path)}`,
     'printf "exists=%s\\n" "$(test -d "$path" && printf yes || printf no)"',
     'pkg="$path/package.json"',
     'printf "package_json=%s\\n" "$(test -f "$pkg" && printf yes || printf no)"',
@@ -11214,6 +11372,11 @@ manifestCommand.command("add").description("Add or replace a machine in the flee
     console.log(JSON.stringify(manifestAdd(machine2), null, 2));
     return;
   }
+  for (const key of ["id", "platform", "workspacePath"]) {
+    if (typeof options[key] !== "string" || !options[key].trim()) {
+      throw new Error(`manifest add requires --${key === "workspacePath" ? "workspace-path" : key} unless --from-stdin is used`);
+    }
+  }
   const packages = Array.isArray(options["package"]) ? options["package"].map((name) => ({ name: String(name) })) : undefined;
   const files = Array.isArray(options["file"]) ? options["file"].map((value) => {
     const [source, target, mode] = String(value).split(":");
@@ -11519,6 +11682,68 @@ program2.command("ssh").description("Choose the best SSH route for a machine").r
   }
   console.log(buildSshCommand(options.machine, options.cmd));
 });
+program2.command("screen").description("Open Screen Sharing (VNC) to a machine using its best live route").argument("[machine]", "Machine identifier").option("--machine <id>", "Machine identifier (alternative to positional arg)").option("--all", "Open every reachable machine", false).option("--print", "Print the vnc:// URL instead of opening it", false).option("-j, --json", "Print JSON output", false).action((machineArg, options) => {
+  if (options.all) {
+    const topology = discoverMachineTopology();
+    const results = topology.machines.map((m) => {
+      try {
+        const resolved2 = resolveScreenTarget(m.machine_id, { topology });
+        return { machine: m.machine_id, ok: true, url: resolved2.url, route: resolved2.route };
+      } catch (error) {
+        return { machine: m.machine_id, ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    });
+    if (options.json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    for (const r of results) {
+      if (r.ok && r.url) {
+        if (!options.print)
+          execFileSync("open", [r.url], { stdio: "ignore" });
+        console.log(`${r.ok ? "\u2713" : "\u2717"} ${r.machine.padEnd(14)} ${r.url ?? r.error}`);
+      } else {
+        console.log(`\u2717 ${r.machine.padEnd(14)} ${r.error}`);
+      }
+    }
+    return;
+  }
+  const machineId = machineArg ?? options.machine;
+  if (!machineId) {
+    console.error("Provide a machine: machines screen <id>  (or --all)");
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = resolveScreenTarget(machineId);
+  if (options.json) {
+    console.log(JSON.stringify(resolved, null, 2));
+    return;
+  }
+  if (options.print) {
+    console.log(resolved.url);
+    return;
+  }
+  execFileSync("open", [resolved.url], { stdio: "ignore" });
+  console.log(`Opening Screen Sharing \u2192 ${resolved.url} (route: ${resolved.route})`);
+});
+program2.command("screen-enable").description("Enable Remote Management / Screen Sharing on a macOS machine over SSH").requiredOption("--machine <id>", "Machine identifier").option("--user <user>", "macOS user to grant screen-sharing (overrides manifest)").option("--vnc-password <pw>", "Legacy VNC password (<=8 chars honored)", "").option("--print", "Print the remote command instead of running it", false).action((options) => {
+  const screen = resolveScreenTarget(options.machine);
+  const user = options.user ?? screen.user;
+  if (!user) {
+    console.error(`No SSH user known for ${options.machine}; pass --user <name> or set metadata.user in the manifest.`);
+    process.exitCode = 1;
+    return;
+  }
+  const vncPw = (options.vncPassword || "").slice(0, 8);
+  const remoteCmd = buildScreenEnableRemoteCommand(user, vncPw);
+  const sshCmd = buildSshCommand(options.machine, `sudo -p '' bash -c ${JSON.stringify(remoteCmd)}`);
+  if (options.print) {
+    console.log(sshCmd);
+    return;
+  }
+  console.log(`Run this to enable Screen Sharing on ${options.machine} (will prompt for sudo on the target):`);
+  console.log(`  ${sshCmd}`);
+});
 program2.command("ports").description("List listening ports on a machine").option("--machine <id>", "Machine identifier").option("-j, --json", "Print JSON output", false).action((options) => {
   const result = listPorts(options.machine);
   console.log(JSON.stringify(result, null, 2));
@@ -11683,4 +11908,10 @@ healCommand.command("uninstall").description("Remove the systemd watchdog servic
   }
   console.log(renderList("uninstall", uninstallHealService()));
 });
-await program2.parseAsync(process.argv);
+try {
+  await program2.parseAsync(process.argv);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(source_default.red(message));
+  process.exit(1);
+}

package/dist/commands/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAGhB,eAAe,EACf,WAAW,EAEZ,MAAM,aAAa,CAAC;AA8FrB,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAM3F;AAED,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAQ7D;AAED,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAWlE;AAED,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CAO3D;AAED,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CA0BhH"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAGhB,eAAe,EACf,WAAW,EAEZ,MAAM,aAAa,CAAC;AA+FrB,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,EAAE,CAAA;CAAE,CAM3F;AAED,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAQ7D;AAED,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAWlE;AAED,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CAO3D;AAED,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CA0BhH"}

package/dist/commands/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/commands/manifest.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,YAAY,IAAI,aAAa,CAE5C;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAOnE;AAED,wBAAgB,+BAA+B,IAAI,aAAa,CAE/D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAErE;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAQ/D;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/commands/manifest.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,YAAY,IAAI,aAAa,CAE5C;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAQnE;AAED,wBAAgB,+BAA+B,IAAI,aAAa,CAE/D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAErE;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAQ/D;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD"}

package/dist/commands/screen.d.ts

@@ -0,0 +1,35 @@
+import { type MachineRouteOptions, type MachineRouteKind, type MachineRouteConfidence } from "../topology.js";
+export interface ResolvedScreenTarget {
+    machineId: string;
+    user: string | null;
+    host: string;
+    url: string;
+    route: MachineRouteKind;
+    confidence: MachineRouteConfidence;
+    warnings: string[];
+}
+/**
+ * Resolve the best screen-sharing (VNC) target for a machine.
+ * Prefers the live LAN route over Tailscale (lower latency for screen sharing),
+ * and always produces a `vnc://user@host` URL when a user is known.
+ */
+export declare function resolveScreenTarget(machineId: string, options?: MachineRouteOptions): ResolvedScreenTarget;
+/**
+ * Build the macOS command that opens Screen Sharing to a machine.
+ * `open vnc://user@host` launches Screen Sharing.app pointed at the resolved route.
+ */
+export declare function buildScreenCommand(machineId: string, options?: MachineRouteOptions): string;
+/**
+ * Build the remote command that ENABLES Remote Management / Screen Sharing on a
+ * macOS target via `kickstart`, plus the SRP + legacy-VNC password tweaks that
+ * make user-password auth work reliably from Screen Sharing.app and ARD.
+ *
+ * `vncPassword` is truncated to 8 chars by the VNC protocol; callers should pass
+ * an <=8 char value (or accept that only the first 8 chars are honored by legacy
+ * VNC clients).
+ *
+ * Returns the shell command to run AS ROOT on the target (caller pipes the sudo
+ * password or runs under an already-root context).
+ */
+export declare function buildScreenEnableRemoteCommand(user: string, vncPassword: string): string;
+//# sourceMappingURL=screen.d.ts.map

package/dist/commands/screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../../src/commands/screen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE5J,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,gBAAgB,CAAC;IACxB,UAAU,EAAE,sBAAsB,CAAC;IACnC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,oBAAoB,CA+B9G;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAG/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAcxF"}

package/dist/commands/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmB,WAAW,EAAa,MAAM,aAAa,CAAC;AAsE3E,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAqB9D;AAED,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CAoC1G"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,WAAW,EAAa,MAAM,aAAa,CAAC;AAsE3E,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAqB9D;AAED,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CAoC1G"}

package/dist/commands/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAA+B,UAAU,EAAE,MAAM,aAAa,CAAC;AAiF3E,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAwB5D;AAwBD,wBAAgB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAyCxG"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAA+B,UAAU,EAAE,MAAM,aAAa,CAAC;AAiF3E,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAwB5D;AAwBD,wBAAgB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CAyCxG"}