@nomac/cli 0.7.0 → 0.9.0

package/src/notarize.mjs

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { parseArgs } from "node:util";
+import { api as defaultApi, CliError } from "./api.mjs";
+
+export const NOTARIZE_HELP = `Usage: nomac notarize <path> [--team ISSUER_ID] [--session ses_…] [--no-wait] [--json]
+       nomac notarize --id ntz_…
+Notarize a Developer ID-signed app, disk image or installer on this folder's Mac (path: an
+.app, .dmg, .pkg or .zip on the Mac, relative to the synced folder). Your App Store Connect
+key stays on NoMac's server; the Mac gets only Apple's upload credentials for this one
+submission. Apple checks it, usually for a few minutes, then the Mac staples the ticket.
+Sign it first with your Developer ID Application certificate (upload it at nomac.app/apple):
+  codesign --force --options runtime --timestamp --sign "Developer ID Application: …" App.app`;
+
+const DONE = new Set(["accepted", "invalid", "rejected", "failed"]);
+
+function describe(view) {
+  switch (view.state) {
+    case "preparing": return `Preparing ${view.path} on the Mac…`;
+    case "uploading": return "Sending it to Apple…";
+    case "in_progress": return "Apple is checking it (usually a few minutes). Keep the Mac running so the ticket can be stapled.";
+    case "stapling": return "Notarized. Stapling the ticket…";
+    case "accepted": return [view.message, ...(view.warnings ?? []).map((issue) => `  warning: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)].join("\n");
+    case "invalid": case "rejected": return [
+      `Apple did not notarize it${view.status_summary ? `: ${view.status_summary}` : "."}`,
+      ...(view.issues ?? []).map((issue) => `  ${issue.severity}: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`),
+      "Sign every binary with your Developer ID certificate, --options runtime and --timestamp, then notarize again.",
+    ].join("\n");
+    case "failed": return [`Not notarized: ${view.error?.message ?? "the notarization failed."}`,
+      ...(view.error?.needs_human?.steps ?? []).map((step, index) => `  ${index + 1}. ${step}`)].join("\n");
+    default: return view.state;
+  }
+}
+
+export async function notarizeCommand(args, { api = defaultApi, print = console.log, store } = {}) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    team: { type: "string" }, session: { type: "string" }, id: { type: "string" }, "no-wait": { type: "boolean" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+  } });
+  if (values.help) return print(NOTARIZE_HELP);
+  let view;
+  if (values.id) {
+    if (positionals.length) throw new CliError("notarize usage", NOTARIZE_HELP);
+    view = await api("GET", `/api/v1/notarizations/${encodeURIComponent(values.id)}`);
+  } else {
+    if (positionals.length !== 1) throw new CliError("notarize usage", NOTARIZE_HELP);
+    const session = values.session ?? store?.load()?.id;
+    if (!session || !/^ses_[A-Za-z0-9_-]{1,80}$/.test(session)) throw new CliError("no Mac", "No Mac for this folder. Start one with nomac start, build and sign the app there, or pass --session ses_….");
+    view = await api("POST", `/api/v1/mac/sessions/${encodeURIComponent(session)}/notarize`, { body: {
+      path: positionals[0], request_key: `cli-notarize-${randomUUID()}`, wait_seconds: values["no-wait"] ? 0 : 50, ...(values.team ? { issuer_id: values.team } : {}),
+    } });
+  }
+  let last = "";
+  const show = (current) => {
+    if (values.json) return;
+    const line = describe(current);
+    if (line !== last) print(line);
+    last = line;
+  };
+  show(view);
+  if (!values["no-wait"]) {
+    while (!DONE.has(view.state)) {
+      view = await api("GET", `/api/v1/notarizations/${encodeURIComponent(view.id)}?wait_seconds=50`);
+      show(view);
+    }
+  } else if (!DONE.has(view.state) && !values.json) {
+    print(`Follow it with: nomac notarize --id ${view.id}`);
+  }
+  if (values.json) print(JSON.stringify(view, null, 2));
+  // The reason is already printed; exit non-zero without saying it twice.
+  if (["invalid", "rejected", "failed"].includes(view.state)) throw Object.assign(new CliError("notarize failed", ""), { friendly: "" });
+  return view;
+}

package/src/publish.mjs

@@ -0,0 +1,76 @@
+import { randomUUID } from "node:crypto";
+import { parseArgs } from "node:util";
+import { api as defaultApi, CliError } from "./api.mjs";
+import { testflightCommand } from "./testflight.mjs";
+
+export const PUBLISH_HELP = `Usage: nomac publish [ipa] [--whats-new TEXT] [--confirm] [--notes TEXT] [--encryption no|yes] [--team ISSUER_ID] [--session ses_…]
+       nomac publish --project prj_… [--build bld_…] [--whats-new TEXT] [--confirm]
+Submit your app for App Review, with your App Store Connect key kept on NoMac's server.
+With an .ipa on this folder's Mac, NoMac sends it first, as nomac testflight does, and waits
+until Apple has processed it. Without one, --project (and --build) name a build already on
+TestFlight; nomac testflight prints both.
+Without --confirm nothing goes to App Review: NoMac stages the version with its build and
+lists every blocker Apple reports. Run it again with --confirm to submit.
+  --whats-new TEXT    What's New in This Version; Apple requires it for every update
+  --force             submit despite red readiness findings (not recommended)`;
+
+/** Apple answers some writes with "pending"; the same key observes the original request. */
+async function settled(api, method, path, body, sleep) {
+  const idempotencyKey = `cli-${path.split("/").at(-1)}-${randomUUID()}`;
+  for (let attempt = 0; ; attempt++) {
+    const result = await api(method, path, { body, idempotencyKey });
+    if (result?.state !== "pending" || attempt >= 24) return result;
+    await sleep(5000);
+  }
+}
+
+function blockers(details) {
+  return [
+    ...(details?.blockers ?? []).map((item) => `  ${item.code}: ${item.detail}`),
+    ...(details?.findings ?? []).map((item) => `  ${item.title}: ${item.fix_hint}`),
+  ];
+}
+
+export async function publishCommand(args, { api = defaultApi, print = console.log, store, sleep = (ms) => new Promise((done) => setTimeout(done, ms)) } = {}) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    project: { type: "string" }, build: { type: "string" }, "whats-new": { type: "string" }, confirm: { type: "boolean" }, force: { type: "boolean" },
+    notes: { type: "string" }, encryption: { type: "string" }, team: { type: "string" }, session: { type: "string" },
+    json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+  } });
+  if (values.help) return print(PUBLISH_HELP);
+  if (positionals.length > 1 || (positionals.length && (values.project || values.build)) || (!positionals.length && !values.project)) throw new CliError("publish usage", PUBLISH_HELP);
+  let project = values.project, build = values.build, version;
+  if (positionals.length) {
+    const sendArgs = [positionals[0], ...["notes", "encryption", "team", "session"].flatMap((name) => values[name] ? [`--${name}`, values[name]] : [])];
+    const sent = await testflightCommand(sendArgs, { api, print: values.json ? () => {} : print, store });
+    ({ project_id: project, build_id: build } = sent);
+    version = sent.app.version;
+  }
+  if (values["whats-new"]) {
+    await settled(api, "PUT", `/api/v1/projects/${encodeURIComponent(project)}/metadata`, { ...(version ? { version_string: version } : {}), fields: { whats_new: values["whats-new"] } }, sleep);
+    if (!values.json) print("What's New is set.");
+  }
+  let result;
+  try {
+    result = await settled(api, "POST", "/api/v1/publish", { project_id: project, ...(build ? { build_id: build } : {}), confirm: Boolean(values.confirm), force: Boolean(values.force) }, sleep);
+  } catch (error) {
+    if (error instanceof CliError && !values.json) {
+      const lines = blockers(error.details);
+      if (lines.length) error.friendly = [error.friendly, "Apple or the readiness check reports:", ...lines].join("\n");
+    }
+    throw error;
+  }
+  if (values.json) { print(JSON.stringify(result, null, 2)); return result; }
+  if (result.state === "pending") {
+    print("Apple has not confirmed yet. Check with nomac publish again in a minute; nothing is sent twice.");
+  } else if (result.staged) {
+    print([
+      `Staged for App Review: build ${result.build_id}. Nothing was sent to App Review.`,
+      ...(result.lint_note ? [`Note: ${result.lint_note}`] : []),
+      `To submit: nomac publish --project ${project} --build ${result.build_id} --confirm`,
+    ].join("\n"));
+  } else {
+    print(`Submitted to App Review (${result.state}). Apple usually decides within one to three days.`);
+  }
+  return result;
+}

package/src/secrets.mjs

@@ -0,0 +1,136 @@
+import { readFileSync, statSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { api as defaultApi, CliError } from "./api.mjs";
+
+export const SECRETS_HELP = `Usage: nomac secrets [command]
+Secrets are variables and files every Mac you start receives. Values never
+come back from NoMac, and are never taken as command-line arguments.
+
+  nomac secrets                          list them (names, where they go, sizes)
+  nomac secrets set NAME                 a variable; the value from stdin, hidden when typed
+  nomac secrets set NAME --file PATH     a file, up to 1 MiB  [--destination ~/.netrc]
+  nomac secrets set --from-env-file .env every NAME=value line as a variable
+      --on-request                       only when asked (install NAME), not on every Mac
+  nomac secrets rm NAME                  delete it
+  nomac secrets install [NAME...]        put them on this folder's Mac now  [--session ses_…]
+  nomac secrets request NAME --description TEXT [--kind file] [--destination ~/x]
+                                         a link where someone enters it in the browser
+Add --json for JSON.`;
+
+/**
+ * Lines of a .env file as variables, as the dashboard's import reads them
+ * (apps/web/lib/env-file.ts): comments, blank lines and `export ` are handled,
+ * quotes keep a # inside, and a value that spans lines is skipped.
+ */
+export function parseEnv(text) {
+  const variables = [], skipped = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) { skipped.push(line.slice(0, 40)); continue; }
+    let value = match[2];
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.length >= 2 && value.endsWith(quote)) value = value.slice(1, -1);
+    else if (quote === '"' || quote === "'") { skipped.push(match[1]); continue; }
+    else value = value.replace(/\s+#.*$/, "");
+    variables.push({ name: match[1], value });
+  }
+  return { variables, skipped };
+}
+
+/** A value from stdin: typed with echo off at a terminal, or piped (one trailing newline dropped). */
+async function readValue(stdin, write) {
+  if (stdin.isTTY) {
+    write("Value (hidden): ");
+    stdin.setRawMode(true); stdin.resume(); stdin.setEncoding("utf8");
+    try {
+      return await new Promise((resolve, reject) => {
+        let value = "";
+        const onData = (chunk) => {
+          for (const char of chunk) {
+            if (char === "\r" || char === "\n") { stdin.off("data", onData); write("\n"); return resolve(value); }
+            if (char === "\u0003") { stdin.off("data", onData); write("\n"); return reject(new CliError("cancelled", "Cancelled.")); }
+            if (char === "\u007f") value = value.slice(0, -1);
+            else value += char;
+          }
+        };
+        stdin.on("data", onData);
+      });
+    } finally { stdin.setRawMode(false); stdin.pause(); }
+  }
+  const chunks = [];
+  for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+
+const size = (bytes) => bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+
+export async function secretsCommand(args, { api = defaultApi, print = console.log, write = (text) => process.stderr.write(text), stdin = process.stdin, store } = {}) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    file: { type: "string" }, "from-env-file": { type: "string" }, destination: { type: "string" }, "on-request": { type: "boolean" },
+    session: { type: "string" }, description: { type: "string" }, kind: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+  } });
+  const [command = "list", ...names] = positionals;
+  if (values.help || command === "help") return print(SECRETS_HELP);
+  const out = (result, text) => { print(values.json ? JSON.stringify(result, null, 2) : text); return result; };
+  const delivery = values["on-request"] ? "on_request" : "every_mac";
+  const path = (name) => `/api/v1/secrets/${encodeURIComponent(name)}`;
+
+  if (command === "list" || command === "ls") {
+    const result = await api("GET", "/api/v1/secrets");
+    const lines = result.secrets.map((secret) => `${secret.name}  ${secret.kind === "variable" ? `$${secret.variable}` : secret.path}  ${size(secret.size)}  ${secret.delivery === "every_mac" ? "every Mac" : "when asked"}`);
+    const waiting = result.pending_requests.map((request) => `${request.name}  requested by an agent, not entered yet`);
+    return out(result, [...lines, ...waiting].join("\n") || "No secrets yet. Add one with nomac secrets set NAME, or on nomac.app/secrets.");
+  }
+  if (command === "set") {
+    if (values["from-env-file"]) {
+      if (names.length || values.file) throw new CliError("set usage", "--from-env-file takes no NAME and no --file.");
+      const { variables, skipped } = parseEnv(readFileSync(values["from-env-file"], "utf8"));
+      const saved = [], failed = [];
+      for (const variable of variables) {
+        try { await api("PUT", path(variable.name), { body: { kind: "variable", value: variable.value, delivery } }); saved.push(variable.name); }
+        catch (error) { failed.push({ name: variable.name, message: error.friendly ?? error.message }); }
+      }
+      const result = { saved, failed, skipped };
+      out(result, [`Saved ${saved.length} of ${variables.length} variables.`, ...failed.map((item) => `${item.name}: ${item.message}`),
+        ...(skipped.length ? [`Skipped lines that are not NAME=value on one line: ${skipped.join(", ")}`] : [])].join("\n"));
+      if (failed.length) process.exitCode = 1;
+      return result;
+    }
+    if (names.length !== 1) throw new CliError("set usage", SECRETS_HELP);
+    let body;
+    if (values.file) {
+      if (statSync(values.file).size > 1024 * 1024) throw new CliError("file too large", "A file secret holds at most 1 MiB.");
+      body = { kind: "file", value_base64: readFileSync(values.file).toString("base64"), destination: values.destination ?? null, delivery };
+    } else {
+      if (values.destination) throw new CliError("set usage", "--destination is for files: add --file PATH.");
+      body = { kind: "variable", value: await readValue(stdin, write), delivery };
+    }
+    const result = await api("PUT", path(names[0]), { body });
+    return out(result, `Saved ${result.secret.name}. New Macs receive it; run nomac secrets install to put it on a running Mac.`);
+  }
+  if (command === "rm" || command === "delete") {
+    if (names.length !== 1) throw new CliError("rm usage", "Usage: nomac secrets rm NAME");
+    const result = await api("DELETE", path(names[0]));
+    return out(result, `Deleted ${names[0]}. Macs started from now on do not receive it; a running Mac keeps its copy until it stops.`);
+  }
+  if (command === "install") {
+    const session = values.session ?? store?.load()?.id;
+    if (!session || !/^ses_[A-Za-z0-9_-]{1,80}$/.test(session)) throw new CliError("no Mac", "No Mac for this folder. Start one with nomac start, or pass --session ses_….");
+    const result = await api("POST", `/api/v1/mac/sessions/${encodeURIComponent(session)}/secrets`, { body: { names } });
+    const installed = result.credentials;
+    return out(result, [`Installed on ${session}: ${installed.state}.`,
+      ...installed.secrets.map((secret) => `  ${secret.kind === "variable" ? `$${secret.name}` : secret.path}`),
+      ...(installed.identities?.length ? [`  ${installed.identities.length} signing identit${installed.identities.length === 1 ? "y" : "ies"}, ${installed.profiles.length} profiles`] : []),
+      ...(installed.message ? [installed.message] : [])].join("\n"));
+  }
+  if (command === "request") {
+    const kind = values.kind ?? "variable";
+    if (names.length !== 1 || !values.description || !["variable", "file"].includes(kind)) throw new CliError("request usage", "Usage: nomac secrets request NAME --description TEXT [--kind file] [--destination ~/x]");
+    const result = await api("POST", "/api/v1/secrets/requests", { body: { name: names[0], kind, description: values.description,
+      ...(values.destination ? { destination: values.destination } : {}), delivery } });
+    return out(result, `Open this link to enter ${result.name} (expires ${result.expires_at}):\n${result.url}`);
+  }
+  throw new CliError("unknown secrets command", SECRETS_HELP);
+}

package/src/session-ssh.mjs

@@ -35,7 +35,9 @@ export function multiplexArgs(session, { platform = process.platform, home = hom
   const dir = join(home, ".nomac", "cm");
   const name = createHash("sha256").update(`${session.id}:${session.generation ?? 0}`).digest("hex").slice(0, 20);
   const path = join(dir, name);
-  if (path.length > 100) return off; // Unix socket paths are limited to about 104 bytes
+  // macOS socket paths hold 103 bytes, and ssh first binds a temporary socket at the path
+  // plus a 17-byte suffix (".XXXXXXXXXXXXXXXX"): longer paths make ssh exit 255.
+  if (Buffer.byteLength(path) > 86) return off;
   try { mkdirSync(dir, { recursive: true, mode: 0o700 }); chmodSync(dir, 0o700); } catch { return off; }
   return ["-o", "ControlMaster=auto", "-o", `ControlPath=${path}`, "-o", "ControlPersist=120"];
 }

package/src/session-transfer.mjs

@@ -1,49 +1,92 @@
 import { createHash, randomUUID } from "node:crypto";
-import { constants, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, chmodSync, utimesSync } from "node:fs";
+import { constants, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, chmodSync, utimesSync } from "node:fs";
 import { basename, 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",
+/**
+ * What sync leaves out unless .nomacignore brings it back: folders that are
+ * rebuilt on the Mac anyway, git history, Finder metadata and NoMac's own
+ * files. Nothing is left out to protect the person from their own files:
+ * .env files, keys and certificates travel like any other file.
+ */
+const BUILT_IN = [
+  { pattern: "node_modules/", reason: "rebuilt on the Mac" },
+  { pattern: "Pods/", reason: "rebuilt on the Mac" },
+  { pattern: "DerivedData/", reason: "rebuilt on the Mac" },
+  { pattern: ".build/", reason: "rebuilt on the Mac" },
+  { pattern: "build/", reason: "rebuilt on the Mac" },
+  { pattern: ".git/", reason: "git history" },
+  { pattern: ".DS_Store", reason: "Finder metadata" },
+  { pattern: ".nomac/", reason: "NoMac's own files" },
+  { pattern: ".nomac.json", reason: "NoMac's own files" },
+  { pattern: ".nomac-transfer/", reason: "NoMac's own files" },
 ];
+// Built-in patterns are names, matched against the entry's own name, so a folder
+// brought back with `!` is never skipped again through its parent.
+const builtInRules = BUILT_IN.map(({ pattern, reason }) => ({ rules: ignoreFactory().add(pattern), reason }));
 
+/** Code-unit order, the same as Array.prototype.sort on the file lists. */
+const byPath = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** The last opinion of a chain of ignore files: true (skip), false (send) or undefined (none). */
+function verdict(scopes, path, isDirectory) {
+  let result;
+  for (const scope of scopes) {
+    const test = scope.rules.test(relative(scope.root, path).split(sep).join("/") + (isDirectory ? "/" : ""));
+    if (test.ignored) result = true;
+    if (test.unignored) result = false;
+  }
+  return result;
+}
+
+/**
+ * The project as sync sends it. Every file is sent, including files a
+ * .gitignore lists (.env, local configuration, temporary files): they are
+ * small and often needed to build. Folders a .gitignore lists are skipped,
+ * because they are dependencies and build output. .nomacignore decides last:
+ * it can skip anything more, and its `!` lines bring back anything, the
+ * built-in skips included. A folder brought back is sent as it is, except
+ * for what .nomacignore itself skips. Symlinks are sent as links and never
+ * followed.
+ */
 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 files = [], links = [], skipped = [];
+  const walk = (directory, gitScopes, nomacScopes, restored) => {
+    const git = [...gitScopes], nomac = [...nomacScopes];
+    for (const [name, list] of [[".gitignore", git], [".nomacignore", nomac]]) {
       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")) });
+      if (existsSync(path) && lstatSync(path).isFile()) list.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;
+      const isDirectory = entry.isDirectory(), candidate = rel + (isDirectory ? "/" : "");
+      let reason;
+      if (!restored) {
+        reason = builtInRules.find(rule => rule.rules.ignores(entry.name + (isDirectory ? "/" : "")))?.reason;
+        if (!reason && isDirectory && verdict(git, path, true)) reason = "listed in .gitignore";
       }
-      if (ignored) continue;
-      if (entry.isSymbolicLink()) skippedLinks.push(rel);
-      else if (entry.isDirectory()) walk(path, scopes);
+      const decision = verdict(nomac, path, isDirectory);
+      const bringsBack = decision === false && reason !== undefined;
+      if (decision === true) reason = "listed in .nomacignore";
+      if (decision === false) reason = undefined;
+      if (reason) { skipped.push({ path: candidate, reason }); continue; }
+      if (entry.isSymbolicLink()) links.push(rel);
+      else if (isDirectory) walk(path, git, nomac, restored || bringsBack);
       else if (entry.isFile()) files.push(rel);
     }
   };
-  walk(root);
-  return { files: files.sort(), skippedLinks: skippedLinks.sort() };
+  walk(root, [], [], false);
+  return { files: files.sort(), links: links.sort(), skipped: skipped.sort((a, b) => byPath(a.path, b.path)) };
 }
 
 export async function fingerprint(path) {
   const stat = lstatSync(path);
-  if (!stat.isFile()) return stat.isSymbolicLink() ? "symlink" : "other";
+  if (stat.isSymbolicLink()) return `link:${createHash("sha256").update(readlinkSync(path, { encoding: "buffer" })).digest("hex")}`;
+  if (!stat.isFile()) return "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)}`;
@@ -68,12 +111,21 @@ 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;
+  pop @parts;
   my $unsafe = 0;
   while (@parts > 1) {
     if (-l join('/', @parts)) { $unsafe = 1; last; }
     pop @parts;
   }
+  # A symlinked folder above the path could send a write outside the workspace.
   if ($unsafe) { $result{$name} = 'symlink'; next; }
+  # The path itself may be a link that sync placed: compare its target, never follow it.
+  if (-l $file) {
+    my $target = readlink($file);
+    die "Cannot read link" unless defined $target;
+    $result{$name} = 'link:' . Digest::SHA::sha256_hex($target);
+    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";
@@ -98,7 +150,7 @@ export async function remoteFingerprints(session, files, options) {
     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");
+      if (typeof value !== "string" || !/^(?:missing|symlink|other|link:[a-f0-9]{64}|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 });
     }
   }
@@ -110,6 +162,30 @@ function transferArgs() {
   return ["-rpt", "--checksum", "--itemize-changes", "--stats", "--timeout=60", "-e", [process.execPath, bridge].map(rsyncQuote).join(" ")];
 }
 
+/** Size, the biggest files, and what was skipped with the .nomacignore line that would send it. */
+function summarize(root, { files, links, skipped }) {
+  const sizes = files.map(path => ({ path, bytes: lstatSync(join(root, path)).size }));
+  return {
+    bytes: sizes.reduce((sum, file) => sum + file.bytes, 0),
+    links: links.length,
+    biggest: sizes.sort((a, b) => b.bytes - a.bytes || byPath(a.path, b.path)).slice(0, 5),
+    skipped: skipped.map(item => ({ ...item, send_with: `!${item.path}` })),
+  };
+}
+
+const megabytes = bytes => `${(bytes / 1_000_000).toFixed(bytes < 10_000_000 ? 1 : 0)} MB`;
+
+/** The human summary of a sync: what changed, how much was considered, and what stayed behind. */
+export function describeSync(result) {
+  const lines = [`${result.dry_run ? "Would sync" : "Synced"} ${result.changed.length} changed of ${result.files} files (${megabytes(result.bytes)}${result.links ? `, ${result.links} links` : ""}).`];
+  if (result.skipped.length) {
+    lines.push("Skipped (add the line to .nomacignore to send it):");
+    for (const item of result.skipped.slice(0, 20)) lines.push(`  ${item.path}  ${item.reason}  ${item.send_with}`);
+    if (result.skipped.length > 20) lines.push(`  …and ${result.skipped.length - 20} more (--json lists all)`);
+  }
+  return lines.join("\n");
+}
+
 const transferEnv = (session, remoteDirectory = ".") => ({ ...process.env, NOMAC_TRANSFER_SESSION: JSON.stringify({ ...session, remoteDirectory }) });
 
 function conflictError(paths, side) {
@@ -120,24 +196,27 @@ function conflictError(paths, side) {
 }
 
 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 selection = projectFiles(store.project);
+  const paths = [...selection.files, ...selection.links].sort();
+  if (!paths.length) throw new CliError("no project files", "Nothing to send: every file is in a skipped folder. Add `!` lines to .nomacignore for what the Mac needs.");
   const local = Object.create(null);
-  for (const path of files) local[path] = await fingerprint(join(store.project, path));
+  for (const path of paths) 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]);
+  const previous = await remoteFingerprints(session, paths, { run });
+  const unsafe = paths.filter(path => ["symlink", "other"].includes(previous[path]));
+  if (unsafe.length) throw new CliError("unsafe remote path", `Remote paths are below a symlinked folder or have incompatible types: ${unsafe.slice(0, 10).join(", ")}. Resolve them inside the workspace first.`);
+  const conflicts = paths.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];
+  const changed = paths.filter(path => previous[path] !== local[path]), summary = summarize(store.project, selection);
+  if (dryRun) return { dry_run: true, files: paths.length, changed, ...summary };
+  // --links sends a symlink as a link: its target is never read or followed.
+  const output = await run("rsync", [...transferArgs(), "--links", "--from0", "--files-from=-", `${store.project}/`, `${session.target}:./`], { input: Buffer.from(paths.join("\0") + "\0"), env: transferEnv(session) });
+  const after = await remoteFingerprints(session, paths, { run });
+  const changedDuringTransfer = paths.filter(path => after[path] !== local[path]);
+  for (const path of paths) 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 };
+  return { files: paths.length, changed, ...summary, output: output.stdout };
 }
 
 /** Refuse symlink ancestors, including the destination itself, before local writes. */
@@ -166,7 +245,7 @@ export async function pullProject(session, store, destination, { from = destinat
   if (kind === "missing") {
     throw new CliError("no such workspace path", `The Mac has no ${from} in its workspace. Paths are relative to the workspace; copy anything outside it, such as /tmp, into the workspace first.`);
   }
-  if (kind === "symlink") throw new CliError("unsafe remote path", `${from} is a symlink. Resolve it inside the workspace first.`);
+  if (kind === "symlink" || kind.startsWith("link:")) throw new CliError("unsafe remote path", `${from} is a symlink. Pull the folder or file it points to instead.`);
   const single = typeof kind === "string" && kind.startsWith("file:") ? posix.basename(from) : null;
   const source = single ? posix.dirname(from) : from;
   // cp semantics for a single file: into the directory if one exists, else to that name.

package/src/sessions.mjs

@@ -5,7 +5,7 @@ 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";
+import { describeSync, pullProject, syncProject } from "./session-transfer.mjs";
 
 export const SESSION_HELP = `Nomac 2.0 — SSH workspace preview
 
@@ -132,7 +132,7 @@ export async function sessionCommand(command, argv, { store: suppliedStore, run
     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(", ")}` : ""}`);
+      return output(result, describeSync(result));
     }
     if (command === "pull") {
       if (positionals.length !== 1) throw new CliError("pull usage", "Usage: nomac pull LOCAL_DIRECTORY [--from REMOTE_DIRECTORY] [--dry-run] [--overwrite]");

package/src/sign.mjs

@@ -0,0 +1,37 @@
+import { parseArgs } from "node:util";
+import { api as defaultApi, CliError } from "./api.mjs";
+
+export const SIGN_HELP = `Usage: nomac sign [path] [--scheme NAME] [--container PATH] [--team ISSUER_ID] [--session ses_…] [--json]
+Set up App Store signing for the project on this folder's Mac (path: the project folder
+on the Mac, relative to the synced folder; default .). NoMac reads the project there,
+makes the App Store profiles its app and extensions need with your App Store Connect key,
+which stays on NoMac's server, and installs them with your certificate. The project
+itself is not changed. Then build with your own tools and the files it prints.`;
+
+export async function signCommand(args, { api = defaultApi, print = console.log, store } = {}) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    scheme: { type: "string" }, container: { type: "string" }, team: { type: "string" }, session: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
+  } });
+  if (values.help) return print(SIGN_HELP);
+  if (positionals.length > 1) throw new CliError("sign usage", SIGN_HELP);
+  const session = values.session ?? store?.load()?.id;
+  if (!session || !/^ses_[A-Za-z0-9_-]{1,80}$/.test(session)) throw new CliError("no Mac", "No Mac for this folder. Start one with nomac start and sync the project (nomac sync .), or pass --session ses_….");
+  const body = { ...(positionals[0] ? { path: positionals[0] } : {}), ...(values.scheme ? { scheme: values.scheme } : {}), ...(values.container ? { container: values.container } : {}), ...(values.team ? { issuer_id: values.team } : {}) };
+  const result = await api("POST", `/api/v1/mac/sessions/${encodeURIComponent(session)}/signing`, { body });
+  if (values.json) { print(JSON.stringify(result, null, 2)); return result; }
+  print([
+    `Signing set up for ${result.project.scheme} (${result.project.container}), Apple team ${result.team_id}, with ${result.identity.name}.`,
+    ...result.changes.map((change) => `  ${change}`),
+    ...result.profiles.map((profile) => `  ${profile.bundle_id}: ${profile.name}, until ${profile.expires_at.slice(0, 10)}`),
+    "",
+    "Build on the Mac with your own tools:",
+    ...result.commands.xcodebuild.map((line) => `  ${line}`),
+    `  Flutter: ${result.commands.flutter}`,
+    `  fastlane: ${result.commands.fastlane}`,
+    ...(result.build_number ? ["", `Build number ${result.build_number} is reserved for this build; the commands set it.`] : []),
+    ...(result.app_record ? ["", `Before TestFlight: ${result.app_record.message}`, `  ${result.app_record.url}`] : []),
+    "",
+    "Then send the .ipa to TestFlight with nomac testflight <path to the .ipa>.",
+  ].join("\n"));
+  return result;
+}