@nomac/cli 0.2.5 → 0.3.0

package/src/mcp.mjs

@@ -11,6 +11,7 @@ import { loadProjectState, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
 import { uploadStoreAsset } from "./store-upload.mjs";
+import { MAC_TOOLS } from "./mac-tools.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
 
@@ -27,6 +28,32 @@ async function resolveProjectId(args) {
 }
 
 export const TOOLS = [
+  ...MAC_TOOLS,
+  {
+    name: "check_project", description: "Free source-readiness check of the latest uploaded snapshot. No Apple credentials or paid compute. Run push_project first or after code changes; this does not prove compilation or TestFlight delivery.",
+    inputSchema: { type: "object", properties: { project_id: { type: "string" } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/check-project", { body: { project_id: await resolveProjectId(args) } })),
+  },
+  {
+    name: "get_billing_status", description: "Read confirmed payment, contracted prices, quota/reset, renewal and first-purchase refund eligibility. After payment, resume a blocked build once with a fresh request_key only if the earlier response said build_started:false. Reconcile unknown outcomes first.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => text(await api("GET", "/api/v1/billing/status")),
+  },
+  {
+    name: "get_checkout_link", description: "Return an org-bound checkout link; the human chooses a plan and pays explicitly. This tool does not charge them. Reuses pending checkout; existing subscribers get billing management instead.",
+    inputSchema: { type: "object", properties: { plan: { type: "string", enum: ["starter", "pro"] } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/checkout", { body: args })),
+  },
+  {
+    name: "request_refund", description: "Preview the first-purchase refund amount and subscription cancellation. Default confirm:false. Present the quote and effect to the customer; only after explicit authorization for both actions call with confirm:true and its request_id. A build failure alone does not authorize a refund. Reason is optional.",
+    inputSchema: { type: "object", properties: { confirm: { type: "boolean", default: false }, request_id: { type: "string" }, reason: { type: "string", maxLength: 1000 } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/refund", { body: args })),
+  },
+  {
+    name: "get_refund_status", description: "Read the saved refund and cancellation progress. Does not submit a refund or cancel anything.",
+    inputSchema: { type: "object", properties: { request_id: { type: "string" } }, required: ["request_id"], additionalProperties: false },
+    handler: async args => text(await api("GET", `/api/v1/billing/refund?request_id=${encodeURIComponent(args.request_id)}`)),
+  },
   {
     name: "upload_store_asset",
     description: "Upload a new Apple screenshot, preview, purchase image, supplemental reviewer attachment or encryption document from file_path (up to 500 MiB, subject to Apple limits) or data_base64 (2 MiB). Discover the createInstance operation/body and parent scope with get_store_capabilities/read_store. Preview by default; confirm:true reserves, uploads and commits. Preserve request_key and identical bytes/body to resume. ready:true requires Apple processing COMPLETE. Message attachments require App Store Connect.",
@@ -114,6 +141,7 @@ export const TOOLS = [
       properties: {
         project_id: { type: "string" },
         workflow: { type: "string", enum: ["release", "smoke"], default: "release" },
+        request_key: { type: "string", description: "Reuse this key to reconcile an unknown response. Use a fresh key after a confirmed build_started:false and payment/setup completion." },
       },
       additionalProperties: false,
     },
@@ -121,7 +149,7 @@ export const TOOLS = [
       const project_id = await resolveProjectId(args);
       const res = await api("POST", "/api/v1/builds", {
         body: { project_id, workflow: args?.workflow ?? "release" },
-        idempotencyKey: `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+        idempotencyKey: args?.request_key ?? `mcp-${randomUUID()}`,
       });
       let warning;
       try {
@@ -335,12 +363,14 @@ export const TOOLS = [
   {
     name: "report_issue",
     description:
-      "File an unknown/unfixable error with nomac support. Auto-attaches build error, logs (redacted) and lint state when you pass ref_id (a bld_… id). Deduped by error fingerprint. An optional email requests a direct resolution update; replies are always available by calling with no description.",
+      "File an unknown/unfixable error with nomac support. For a Mac use session_id and optional job_id; for a build use ref_id (bld_…). Attaches account-scoped context and deduplicates repeats. An optional email requests a direct resolution update; replies are always available by calling with no description.",
     inputSchema: {
       type: "object",
       properties: {
         description: { type: "string", description: "what went wrong + what you tried (≥10 chars). Omit to read existing tickets/replies." },
         ref_id: { type: "string" },
+        session_id: { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" },
+        job_id: { type: "string", pattern: "^job_[a-f0-9]{40}$" },
         email: {
           type: "string",
           format: "email",
@@ -400,7 +430,7 @@ export async function runMcpServer() {
             reply(await tool.handler(params?.arguments ?? {}));
           } catch (err) {
             reply({
-              content: [{ type: "text", text: err?.friendly ?? err?.message ?? String(err) }],
+              content: [{ type: "text", text: err?.details ? JSON.stringify({ error: { ...err.details, message: err.friendly ?? err.message } }, null, 2) : err?.friendly ?? err?.message ?? String(err) }],
               isError: true,
             });
           }

package/src/session-ssh.mjs

@@ -0,0 +1,135 @@
+import { spawn } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./api.mjs";
+
+export const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+export function validateTarget(target) {
+  // A hostname or user-owned SSH config alias, never command-line options or a shell expression.
+  if (typeof target !== "string" || !/^(?:[a-zA-Z0-9_][a-zA-Z0-9_.-]*@)?[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(target)) {
+    throw new CliError("invalid SSH target", "Use --host user@hostname or an alias from your SSH config. For IPv6, configure an SSH alias first.", undefined, "invalid_ssh_target");
+  }
+  return target;
+}
+
+export function validateWorkspace(path) {
+  if (typeof path !== "string" || !path.startsWith("/") || path === "/" || /[\x00-\x1f\x7f]/.test(path) || path.split("/").some(part => part === ".." || part === ".")) {
+    throw new CliError("invalid workspace", "The Mac returned an invalid workspace path.");
+  }
+  return path;
+}
+
+export function sshArgs(session, { batch = true } = {}) {
+  validateTarget(session.target);
+  if (session.port !== undefined && (!Number.isInteger(session.port) || session.port < 1 || session.port > 65535)) throw new CliError("invalid SSH port");
+  if (session.identity && (!isAbsolute(session.identity) || /[\x00-\x1f\x7f]/.test(session.identity))) throw new CliError("invalid identity path");
+  if (session.mode === "hosted") {
+    if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(session.id) || !isAbsolute(session.knownHosts ?? "") || /[\x00-\x1f\x7f]/.test(session.knownHosts)) throw new CliError("invalid hosted SSH state");
+  }
+  return [
+    ...(session.mode === "hosted" ? ["-F", "/dev/null", "-o", `UserKnownHostsFile=${session.knownHosts}`, "-o", "GlobalKnownHostsFile=/dev/null",
+      "-o", `HostKeyAlias=nomac-${session.id}`, "-o", `ProxyCommand=${[process.execPath, fileURLToPath(new URL("../bin/nomac.mjs", import.meta.url)), "tunnel", session.id].map(shellQuote).join(" ")}`] : []),
+    "-o", "StrictHostKeyChecking=yes", "-o", "ForwardAgent=no",
+    "-o", "ConnectTimeout=15", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3",
+    // Avoid reusing a separately owned master connection with different authentication/forwarding.
+    "-o", "ControlMaster=no", "-o", "ControlPath=none",
+    ...(batch ? ["-o", "BatchMode=yes", "-o", "ClearAllForwardings=yes"] : []),
+    ...(session.port ? ["-p", String(session.port)] : []),
+    ...(session.identity ? ["-i", session.identity, "-o", "IdentitiesOnly=yes"] : []),
+  ];
+}
+
+export function runProcess(program, args, { input, inherit = false, maxBytes = 8 * 1024 * 1024, timeoutMs, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(program, args, { shell: false, stdio: inherit ? "inherit" : ["pipe", "pipe", "pipe"], ...(env ? { env } : {}) });
+    const output = [], errors = [];
+    let bytes = 0, failure, timer;
+    const stop = (message) => { failure = new CliError(message); child.kill("SIGTERM"); };
+    if (timeoutMs) timer = setTimeout(() => stop("Remote operation timed out; inspect its outcome before retrying."), timeoutMs);
+    if (!inherit) {
+      for (const [stream, chunks] of [[child.stdout, output], [child.stderr, errors]]) {
+        stream.on("data", chunk => {
+          bytes += chunk.length;
+          if (bytes > maxBytes) stop("Command output exceeded the capture limit. Run the command through nomac ssh to stream its output.");
+          else chunks.push(chunk);
+        });
+      }
+      child.stdin.on("error", error => { if (error.code !== "EPIPE") failure = error; });
+      child.stdin.end(input);
+    }
+    child.on("error", error => {
+      clearTimeout(timer);
+      reject(new CliError(error.message, error.code === "ENOENT" ? `${program} is required but was not found in PATH.` : error.message, undefined, error.code === "ENOENT" ? "tool_missing" : "process_failed"));
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (failure) return reject(failure);
+      const result = { code: code ?? 1, signal, stdout: Buffer.concat(output).toString("utf8"), stderr: Buffer.concat(errors).toString("utf8") };
+      if (code !== 0) {
+        const error = new CliError(`${program} exited ${code ?? signal}`, result.stderr.trim() || `${program} exited ${code ?? signal}`, undefined, program === "ssh" ? "ssh_failed" : "transfer_failed");
+        error.exitCode = code && code > 0 ? code : 1;
+        error.result = result;
+        return reject(error);
+      }
+      resolve(result);
+    });
+  });
+}
+
+export function remote(session, script, { run = runProcess, ...options } = {}) {
+  return run("ssh", [...sshArgs(session), session.target, script], { timeoutMs: 60_000, ...options });
+}
+
+/** Does not install a project pipeline or run source code. Creates only this owned workspace. */
+export async function prepareWorkspace(session, options) {
+  if (!/^nms_[a-f0-9]{32}$/.test(session.id)) throw new CliError("invalid session id");
+  const location = session.workspace
+    ? shellQuote(validateWorkspace(session.workspace))
+    : `"$HOME/.nomac/workspaces/${session.id}"`;
+  const script = [
+    'test "$(uname -s)" = Darwin || { echo "Nomac needs a macOS host." >&2; exit 1; }',
+    "command -v rsync >/dev/null || { echo 'Install rsync on the Mac before using file transfer.' >&2; exit 1; }",
+    "perl -MJSON::PP -MDigest::SHA -MEncode -MFcntl -e 'exit 0' || { echo 'Perl checksum and JSON modules are required for file conflict checks.' >&2; exit 1; }",
+    `umask 077; mkdir -p ${location} && cd ${location} || exit 1`,
+    "pwd -P", "sw_vers -productVersion", "uname -m",
+    'if [ "$(id -u)" = 0 ]; then echo admin; else id -Gn; fi', "df -Pk . | tail -1 | awk '{print $4}'",
+  ].join("\n");
+  const { stdout } = await remote(session, script, options);
+  const lines = stdout.trimEnd().split("\n");
+  if (lines.length !== 5) throw new CliError("unexpected Mac response", "The SSH shell printed unexpected output. Ensure non-interactive startup files are quiet, then retry nomac start.");
+  const [workspace, osVersion, architecture, groups, availableKb] = lines;
+  validateWorkspace(workspace);
+  if (!/^[0-9]+(?:\.[0-9]+)*$/.test(osVersion) || !/^[a-zA-Z0-9_]+$/.test(architecture) || !/^\d+$/.test(availableKb)) throw new CliError("invalid Mac capabilities");
+  const admin = groups.split(/\s+/).includes("admin");
+  if (!admin) throw new CliError("administrator account required", "This account is not a macOS administrator. Use an administrator account for a full Nomac workspace.");
+  return { workspace, capabilities: { os: "macOS", version: osVersion, architecture, administrator: admin, available_disk_bytes: Number(availableKb) * 1024 } };
+}
+
+export function workspaceCommand(session, args = []) {
+  const command = args.length ? args.map(shellQuote).join(" ") : '"$SHELL" -l';
+  return `cd ${shellQuote(validateWorkspace(session.workspace))} && exec ${command}`;
+}
+
+export function forwardingArg(value) {
+  const match = /^(\d{1,5}):(\d{1,5})$/.exec(value);
+  if (!match || match.slice(1).some(port => Number(port) < 1 || Number(port) > 65535)) throw new CliError("invalid port mapping", "Use --forward LOCAL_PORT:REMOTE_PORT, for example --forward 8080:3000.");
+  return `127.0.0.1:${Number(match[1])}:127.0.0.1:${Number(match[2])}`;
+}
+
+/** rsync has its own argument parser, not a POSIX shell: quoted apostrophes double. */
+export const rsyncQuote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+
+export function rsyncServerCommand(session, argv, from = ".") {
+  const index = argv.findIndex((arg, i) => arg === "rsync" && argv[i + 1] === "--server");
+  if (index === -1) throw new CliError("invalid rsync server command");
+  const source = String(from);
+  if (source.startsWith("/") || source.split("/").includes("..") || /[\x00-\x1f\x7f\\]/.test(source)) throw new CliError("invalid transfer source");
+  return [
+    `cd ${shellQuote(validateWorkspace(session.workspace))} || exit 1`,
+    `p=${shellQuote(source === "." ? "." : `./${source}`)}`,
+    'while [ "$p" != . ]; do test ! -L "$p" || exit 1; p=$(dirname "$p"); done',
+    `cd ${shellQuote(source)} || exit 1`,
+    `exec ${argv.slice(index).map(shellQuote).join(" ")}`,
+  ].join("\n");
+}

package/src/session-store.mjs

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CliError } from "./api.mjs";
+
+/** Session metadata stays outside the project: a checkout cannot choose an SSH target. */
+export function sessionStore(projectDir = process.cwd(), stateDir = join(homedir(), ".nomac", "sessions")) {
+  const project = realpathSync(projectDir);
+  const name = createHash("sha256").update(project).digest("hex").slice(0, 24);
+  const directory = join(stateDir, name);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  const stateFile = join(directory, "session.json");
+  const baselineFile = join(directory, "baseline.json");
+  const read = (file) => {
+    if (!existsSync(file)) return null;
+    try { return JSON.parse(readFileSync(file, "utf8")); }
+    catch { throw new CliError("invalid session state", `Cannot read ${file}. Restore it before continuing; no remote operation was started.`); }
+  };
+  const write = (file, data) => {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, JSON.stringify(data, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+      renameSync(temporary, file);
+    } finally { rmSync(temporary, { force: true }); }
+  };
+  return {
+    project, directory,
+    load: () => read(stateFile),
+    save: (value) => write(stateFile, value),
+    baseline: () => read(baselineFile) ?? {},
+    saveBaseline: (value) => write(baselineFile, value),
+    async locked(operation) {
+      const lock = join(directory, "operation.lock");
+      try { mkdirSync(lock, { mode: 0o700 }); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        throw new CliError("session busy", `Another session operation is running. If it was interrupted, verify it has ended before removing ${lock}.`);
+      }
+      try { return await operation(); }
+      finally { rmSync(lock, { recursive: true, force: true }); }
+    },
+  };
+}

package/src/session-transfer.mjs

@@ -0,0 +1,215 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, chmodSync, utimesSync } from "node:fs";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ignoreFactory from "ignore";
+import { CliError } from "./api.mjs";
+import { remote, rsyncQuote, runProcess, shellQuote, validateWorkspace } from "./session-ssh.mjs";
+
+const EXCLUDED = [
+  ".git/", ".nomac/", ".nomac.json", ".nomac-transfer/", "node_modules/", "Pods/", "build/", "dist/", "DerivedData/", ".build/", ".next/",
+  ".env", ".env.*", "*.p8", "*.p12", "*.pem", "*.key", "*.mobileprovision", ".ssh/", ".aws/", ".netrc", ".npmrc", "id_rsa*", "id_ed25519*", ".DS_Store",
+];
+
+export function projectFiles(root) {
+  const denied = ignoreFactory().add(EXCLUDED);
+  const files = [], skippedLinks = [];
+  const walk = (directory, inherited = []) => {
+    const scopes = [...inherited];
+    for (const name of [".gitignore", ".nomacignore"]) {
+      const path = join(directory, name);
+      // Ignore files themselves must not read through a symlink outside the project.
+      if (existsSync(path) && lstatSync(path).isFile()) scopes.push({ root: directory, rules: ignoreFactory().add(readFileSync(path, "utf8")) });
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name), rel = relative(root, path).split(sep).join("/");
+      const candidate = rel + (entry.isDirectory() ? "/" : "");
+      if (denied.ignores(candidate)) continue;
+      let ignored = false;
+      for (const scope of scopes) {
+        const result = scope.rules.test(relative(scope.root, path).split(sep).join("/") + (entry.isDirectory() ? "/" : ""));
+        if (result.ignored) ignored = true;
+        if (result.unignored) ignored = false;
+      }
+      if (ignored) continue;
+      if (entry.isSymbolicLink()) skippedLinks.push(rel);
+      else if (entry.isDirectory()) walk(path, scopes);
+      else if (entry.isFile()) files.push(rel);
+    }
+  };
+  walk(root);
+  return { files: files.sort(), skippedLinks: skippedLinks.sort() };
+}
+
+export async function fingerprint(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile()) return stat.isSymbolicLink() ? "symlink" : "other";
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path, { flags: constants.O_RDONLY | constants.O_NOFOLLOW })) hash.update(chunk);
+  return `file:${hash.digest("hex")}:${(stat.mode & 0o777).toString(8)}`;
+}
+
+export function safeRelative(path) {
+  if (typeof path !== "string" || isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\x00-\x1f\x7f]/.test(path) || path.includes("\\")) throw new CliError("invalid relative path", "Use a path within the workspace, without '..' or control characters.");
+  return posix.normalize(path || ".").replace(/\/$/, "") || ".";
+}
+
+// One process per batch, rather than launching shasum/stat for every source file.
+// These Perl modules ship with the Perl used by macOS's checksum tools.
+const REMOTE_FINGERPRINTS = `
+use strict; use warnings;
+use JSON::PP; use Digest::SHA; use Encode qw(encode_utf8);
+use Fcntl qw(O_RDONLY O_NOFOLLOW);
+my $json = JSON::PP->new->utf8;
+my $names = $json->decode(do { local $/; <STDIN> });
+die "Invalid file list" unless ref($names) eq 'ARRAY';
+my %result;
+for my $name (@$names) {
+  die "Invalid path" if ref($name) || $name =~ m{^/|(?:^|/)\\.\\.(?:/|$)|[\\x00-\\x1f\\x7f\\\\]};
+  my $file = './' . encode_utf8($name);
+  my @parts = split m{/}, $file;
+  my $unsafe = 0;
+  while (@parts > 1) {
+    if (-l join('/', @parts)) { $unsafe = 1; last; }
+    pop @parts;
+  }
+  if ($unsafe) { $result{$name} = 'symlink'; next; }
+  if (!-e $file) { $result{$name} = 'missing'; next; }
+  if (!-f $file) { $result{$name} = 'other'; next; }
+  sysopen(my $handle, $file, O_RDONLY | O_NOFOLLOW) or die "Cannot open source file";
+  binmode($handle);
+  my $mode = sprintf('%o', (stat($handle))[2] & 0777);
+  my $digest = Digest::SHA->new(256)->addfile($handle)->hexdigest;
+  close($handle);
+  $result{$name} = "file:$digest:$mode";
+}
+print $json->encode(\\%result);
+`;
+
+export async function remoteFingerprints(session, files, options) {
+  const result = Object.create(null);
+  for (let offset = 0; offset < files.length; offset += 1000) {
+    const batch = files.slice(offset, offset + 1000);
+    for (const path of batch) safeRelative(path);
+    const script = `cd ${shellQuote(validateWorkspace(session.workspace))} && perl -e ${shellQuote(REMOTE_FINGERPRINTS)}`;
+    const { stdout } = await remote(session, script, { ...options, input: JSON.stringify(batch) });
+    let values;
+    try { values = JSON.parse(stdout); } catch { throw new CliError("invalid remote file response"); }
+    if (!values || Array.isArray(values) || Object.keys(values).length !== batch.length) throw new CliError("invalid remote file response");
+    for (const path of batch) {
+      const value = Object.hasOwn(values, path) && values[path];
+      if (typeof value !== "string" || !/^(?:missing|symlink|other|file:[a-f0-9]{64}:[0-7]{1,4})$/.test(value)) throw new CliError("invalid remote fingerprint");
+      Object.defineProperty(result, path, { value, enumerable: true, configurable: true, writable: true });
+    }
+  }
+  return result;
+}
+
+function transferArgs() {
+  const bridge = fileURLToPath(new URL("../bin/rsync-ssh.mjs", import.meta.url));
+  return ["-rpt", "--checksum", "--itemize-changes", "--stats", "--timeout=60", "-e", [process.execPath, bridge].map(rsyncQuote).join(" ")];
+}
+
+const transferEnv = (session, remoteDirectory = ".") => ({ ...process.env, NOMAC_TRANSFER_SESSION: JSON.stringify({ ...session, remoteDirectory }) });
+
+function conflictError(paths, side) {
+  const error = new CliError("transfer conflict", `${side} changes would be overwritten: ${paths.slice(0, 10).join(", ")}. Retrieve/reconcile the changes first, or explicitly use --overwrite.`);
+  error.code = "transfer_conflict";
+  error.details = { paths, side };
+  return error;
+}
+
+export async function syncProject(session, store, { overwrite = false, dryRun = false, run = runProcess } = {}) {
+  const { files, skippedLinks } = projectFiles(store.project);
+  if (!files.length) throw new CliError("no project files", "No files remain after .gitignore, .nomacignore and default exclusions.");
+  const local = Object.create(null);
+  for (const path of files) local[path] = await fingerprint(join(store.project, path));
+  const baseline = Object.assign(Object.create(null), store.baseline());
+  const previous = await remoteFingerprints(session, files, { run });
+  const unsafe = files.filter(path => ["symlink", "other"].includes(previous[path]));
+  if (unsafe.length) throw new CliError("unsafe remote path", `Remote paths are symlinks or have incompatible types: ${unsafe.slice(0, 10).join(", ")}. Resolve them inside the workspace first.`);
+  const conflicts = files.filter(path => previous[path] !== "missing" && previous[path] !== local[path] && previous[path] !== baseline[path]);
+  if (conflicts.length && !overwrite) throw conflictError(conflicts, "Remote");
+  if (dryRun) return { dry_run: true, files: files.length, changed: files.filter(path => previous[path] !== local[path]), skipped_symlinks: skippedLinks };
+  const output = await run("rsync", [...transferArgs(), "--from0", "--files-from=-", `${store.project}/`, `${session.target}:./`], { input: Buffer.from(files.join("\0") + "\0"), env: transferEnv(session) });
+  const after = await remoteFingerprints(session, files, { run });
+  const changedDuringTransfer = files.filter(path => after[path] !== local[path]);
+  for (const path of files) if (after[path] === local[path]) baseline[path] = local[path];
+  store.saveBaseline(baseline);
+  if (changedDuringTransfer.length) throw new CliError("transfer changed during verification", "Some files changed during transfer. Stop concurrent edits and rerun sync; verified files were recorded.");
+  return { files: files.length, changed: files.filter(path => previous[path] !== local[path]), skipped_symlinks: skippedLinks, output: output.stdout };
+}
+
+/** Refuse symlink ancestors, including the destination itself, before local writes. */
+export function assertSafeDestination(root, target) {
+  const rel = relative(root, target);
+  if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) throw new CliError("destination escapes project");
+  let current = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) throw new CliError("unsafe local path", `Refusing to write through symlink: ${current}`); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+export async function pullProject(session, store, destination, { from = destination, overwrite = false, dryRun = false, run = runProcess } = {}) {
+  destination = safeRelative(destination); from = safeRelative(from);
+  const localRoot = resolve(store.project, destination);
+  assertSafeDestination(store.project, localRoot);
+  const staging = mkdtempSync(join(store.directory, "pull-"));
+  const backup = join(store.directory, "backups", randomUUID());
+  try {
+    // Download into an empty private directory; rsync never receives the user's working tree as destination.
+    await run("rsync", [...transferArgs(), `${session.target}:./`, `${staging}/`], { env: transferEnv(session, from) });
+    const files = [];
+    const walk = (directory) => {
+      for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) walk(path);
+        else if (entry.isFile()) files.push(relative(staging, path));
+        else throw new CliError("unsupported download entry", "The download contains a symlink or special file. Retrieve it explicitly over SSH after reviewing it.");
+      }
+    };
+    walk(staging);
+    const baseline = Object.assign(Object.create(null), store.baseline()), plan = [], conflicts = [];
+    for (const path of files) {
+      const target = join(localRoot, path), incoming = await fingerprint(join(staging, path));
+      assertSafeDestination(store.project, target);
+      const current = existsSync(target) ? await fingerprint(target) : "missing";
+      if (current === "other") throw new CliError("incompatible local path", `A directory or special file occupies ${target}.`);
+      const remotePath = from === "." ? path : `${from.replace(/\/$/, "")}/${path}`;
+      // A baseline is meaningful only when downloading to the original project-relative path.
+      const samePath = relative(store.project, target).split(sep).join("/") === remotePath.split(sep).join("/");
+      if (current !== "missing" && current !== incoming && (!samePath || baseline[remotePath] !== current)) conflicts.push(path);
+      plan.push({ path, target, current, incoming, remotePath, samePath });
+    }
+    if (conflicts.length && !overwrite) throw conflictError(conflicts, "Local");
+    if (dryRun) return { dry_run: true, files: files.length, changed: plan.filter(file => file.current !== file.incoming).map(file => file.path) };
+    let backups = false;
+    for (const file of plan) {
+      assertSafeDestination(store.project, file.target);
+      const current = existsSync(file.target) ? await fingerprint(file.target) : "missing";
+      if (current !== file.current) throw new CliError("local file changed", "A local file changed during pull. Stop concurrent edits and retry. Earlier replacements have recovery copies.");
+      if (current !== file.incoming) {
+        mkdirSync(dirname(file.target), { recursive: true });
+        if (current !== "missing") {
+          const recovery = join(backup, file.path);
+          mkdirSync(dirname(recovery), { recursive: true, mode: 0o700 });
+          copyFileSync(file.target, recovery, constants.COPYFILE_EXCL);
+          backups = true;
+        }
+        const temporary = join(dirname(file.target), `.nomac-download-${randomUUID()}`);
+        try {
+          const sourcePath = join(staging, file.path), stat = lstatSync(sourcePath);
+          copyFileSync(sourcePath, temporary, constants.COPYFILE_EXCL);
+          chmodSync(temporary, stat.mode & 0o777);
+          utimesSync(temporary, stat.atime, stat.mtime);
+          renameSync(temporary, file.target);
+        } finally { rmSync(temporary, { force: true }); }
+      }
+      if (file.samePath) baseline[file.remotePath] = file.incoming;
+    }
+    store.saveBaseline(baseline);
+    return { files: files.length, changed: plan.filter(file => file.current !== file.incoming).map(file => file.path), ...(backups ? { recovery_directory: backup } : {}) };
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+}

package/src/sessions.mjs

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CliError } from "./api.mjs";
+import { sessionStore } from "./session-store.mjs";
+import { forwardingArg, prepareWorkspace, runProcess, shellQuote, sshArgs, validateTarget, workspaceCommand } from "./session-ssh.mjs";
+import { pullProject, syncProject } from "./session-transfer.mjs";
+
+export const SESSION_HELP = `Nomac 2.0 — SSH workspace preview
+
+First connection (use a dedicated Mac you control):
+  nomac start --host dev@my-mac [--identity ~/.ssh/id_ed25519] [--port 22]
+
+Then, from the same local project:
+  nomac start                 reconnect to the same Mac workspace
+  nomac sync .                upload changed project files
+  nomac sync --dry-run        inspect changes before uploading
+  nomac ssh                   open a normal shell in the workspace
+  nomac ssh -- node --version run any command (quote shell scripts explicitly)
+  nomac ssh --forward 8080:3000
+  nomac pull ./output         download a remote directory into ./output
+  nomac pull .                bring remote source changes back, with conflict checks
+  nomac session status --json inspect connection, capabilities and ownership
+  nomac stop                  detach locally; the externally owned Mac stays running
+
+Options:
+  sync/pull --overwrite       explicitly replace conflicting files
+  pull --from PATH           choose a different remote directory
+  start/sync/pull/stop --json return machine-readable results
+
+Requires OpenSSH and rsync locally; macOS, rsync and Perl checksum/JSON modules remotely.
+SSH host keys must already be verified in your known_hosts. Your SSH config/agent
+can authenticate; private keys never leave this device. Passwordless sudo is not
+assumed. Use .nomacignore and .gitignore for project exclusions. Symlinks are
+omitted in this preview; use Git/SSH explicitly for projects that need them.
+
+This preview connects an existing Mac. It does not rent hardware, meter charges,
+revoke the owner's SSH access or shut down the Mac. Stop detaches this CLI only;
+existing connections and remote processes continue. Manage rentals with their owner.`;
+
+const commonOptions = { help: { type: "boolean" }, json: { type: "boolean" } };
+const commandOptions = {
+  start: { host: { type: "string" }, identity: { type: "string" }, port: { type: "string" } },
+  sync: { overwrite: { type: "boolean" }, "dry-run": { type: "boolean" } },
+  pull: { overwrite: { type: "boolean" }, "dry-run": { type: "boolean" }, from: { type: "string" } },
+  ssh: { forward: { type: "string", multiple: true } },
+  stop: {}, session: {},
+};
+
+export function describeSession(session) {
+  return {
+    id: session.id, mode: "external_ssh", state: session.state,
+    connection: { target: session.target, port: session.port ?? null, ...(session.identity ? { identity_file: session.identity } : {}) },
+    workspace: session.workspace ?? null, capabilities: session.capabilities ?? null,
+    ssh_command: session.workspace ? ["ssh", ...sshArgs(session, { batch: false }), session.target, workspaceCommand(session)].map(shellQuote).join(" ") : null,
+    checked_at: session.checkedAt ?? null,
+    billing: { managed_by: "mac_owner", nomac_compute_charges: false, rental_end_confirmed: false },
+    retention: "The Mac owner controls retention. Disconnecting or detaching does not remove the workspace.",
+    access_revoked: false, machine_stopped: false,
+  };
+}
+
+function requireReady(store) {
+  const session = store.load();
+  if (!session || session.state !== "ready") throw new CliError("no active workspace", "Run nomac start first. For a new project, use nomac start --host user@mac.", undefined, "no_active_session");
+  if (session.mode !== "external_ssh") throw new CliError("unsupported session mode");
+  return session;
+}
+
+export async function sessionCommand(command, argv, { store: suppliedStore, run = runProcess, print = console.log } = {}) {
+  let parsed;
+  try { parsed = parseArgs({ args: argv, options: { ...commonOptions, ...commandOptions[command] }, allowPositionals: true }); }
+  catch (error) { throw new CliError("invalid session options", `${error.message}\nRun nomac ${command} --help.`); }
+  const { values, positionals } = parsed;
+  if (values.help) return print(SESSION_HELP);
+  const store = suppliedStore ?? sessionStore();
+  const output = (result, summary) => print(values.json ? JSON.stringify(result, null, 2) : summary);
+
+  if (command === "session") {
+    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("session usage", "Usage: nomac session status [--json]");
+    const session = store.load();
+    if (!session) throw new CliError("no workspace", "Run nomac start --host user@mac first.");
+    const result = describeSession(session);
+    return output(result, `${session.state}: ${session.target}\nWorkspace: ${session.workspace ?? "not connected"}\nLast checked: ${session.checkedAt ?? "never"}\nThis is cached status. Run nomac start to check the Mac.\nThe Mac owner controls charges and retention.`);
+  }
+
+  if (command === "ssh") {
+    if (values.json) throw new CliError("SSH is a byte stream", "Use nomac session status --json for connection metadata; SSH streams the remote command directly.");
+    const session = requireReady(store);
+    const forward = (values.forward ?? []).flatMap(value => ["-L", forwardingArg(value)]);
+    const terminal = !positionals.length && process.stdin.isTTY && process.stdout.isTTY;
+    return run("ssh", [...sshArgs(session, { batch: false }), ...(terminal ? ["-t"] : []), ...forward,
+      "-o", "ExitOnForwardFailure=yes", session.target, workspaceCommand(session, positionals)], { inherit: true });
+  }
+
+  return store.locked(async () => {
+    if (command === "start") {
+      if (positionals.length) throw new CliError("start usage", "Usage: nomac start [--host user@mac] [--identity PATH] [--port PORT]");
+      let session = store.load();
+      if (values.host && session?.state === "ready" && session.target !== values.host) throw new CliError("workspace already active", "Run nomac stop before selecting another Mac. Your existing remote files will remain on that Mac.");
+      const target = validateTarget(values.host ?? session?.target ?? "");
+      if (!session || session.target !== target) {
+        session = { id: `nms_${randomUUID().replaceAll("-", "")}`, mode: "external_ssh", state: "connecting", target, createdAt: new Date().toISOString() };
+        store.saveBaseline({});
+      }
+      if (values.port) {
+        if (!/^\d+$/.test(values.port) || Number(values.port) < 1 || Number(values.port) > 65535) throw new CliError("invalid SSH port");
+        session.port = Number(values.port);
+      }
+      if (values.identity) {
+        const identity = resolve(values.identity);
+        if (!existsSync(identity)) throw new CliError("identity missing", `SSH identity file does not exist: ${identity}`);
+        session.identity = realpathSync(identity);
+      }
+      session.state = "connecting";
+      store.save(session); // Retain the same workspace ID if the connection response is lost.
+      const prepared = await prepareWorkspace(session, { run });
+      Object.assign(session, prepared, { state: "ready", checkedAt: new Date().toISOString() });
+      store.save(session);
+      return output(describeSession(session), `Connected to macOS ${prepared.capabilities.version} on ${target}\nWorkspace: ${prepared.workspace}\nNext: nomac sync .  →  nomac ssh\nExisting-Mac preview: rental and retention remain managed by the Mac owner.`);
+    }
+    if (command === "stop") {
+      if (positionals.length) throw new CliError("stop usage", "Usage: nomac stop [--json]");
+      const session = store.load();
+      if (!session) return output({ state: "detached", machine_stopped: false, access_revoked: false }, "No workspace is attached.");
+      session.state = "detached";
+      store.save(session);
+      return output(describeSession(session), "Detached locally. Existing SSH connections, remote processes and files remain.\nThis does not shut down the Mac, revoke owner access or end a rental.\nRun nomac start to reconnect to the same workspace.");
+    }
+    const session = requireReady(store);
+    if (command === "sync") {
+      if (positionals.length > 1 || (positionals[0] && realpathSync(resolve(positionals[0])) !== store.project)) throw new CliError("sync project mismatch", "Run nomac sync . from the project used by nomac start.");
+      const result = await syncProject(session, store, { overwrite: values.overwrite, dryRun: values["dry-run"], run });
+      return output(result, `${result.dry_run ? "Would sync" : "Synced"} ${result.changed.length} changed files (${result.files} considered).${result.skipped_symlinks.length ? `\nSkipped symlinks: ${result.skipped_symlinks.join(", ")}` : ""}`);
+    }
+    if (command === "pull") {
+      if (positionals.length !== 1) throw new CliError("pull usage", "Usage: nomac pull LOCAL_DIRECTORY [--from REMOTE_DIRECTORY] [--dry-run] [--overwrite]");
+      const result = await pullProject(session, store, positionals[0], { from: values.from ?? positionals[0], overwrite: values.overwrite, dryRun: values["dry-run"], run });
+      return output(result, `${result.dry_run ? "Would retrieve" : "Retrieved"} ${result.changed.length} changed files (${result.files} considered).${result.recovery_directory ? `\nPrevious local files: ${result.recovery_directory}` : ""}`);
+    }
+    throw new CliError("unknown session command");
+  });
+}