@nissyai/desktop 0.2.36 → 0.2.38

package/bin/nissy.mjs

@@ -33,10 +33,36 @@ import {
   unsafeArchiveEntries,
   UnsupportedPlatformError,
 } from "../src/resolve.mjs";
+import { confirmHealthyStart, prepareStore } from "../src/store.mjs";
+import { launcherCommand, runLauncherCommand } from "../src/cli.mjs";
 import { DISTRIBUTION } from "../src/distribution.mjs";
 
 const require = createRequire(import.meta.url);
 
+/** npm's copy of the payload version, or null when it cannot be read — an
+ *  uninstalled or half-installed payload, which is precisely the state
+ *  `--version` exists to describe rather than fall over on. */
+function readPayloadVersion() {
+  try {
+    const spec = resolvePayloadSpec(process.platform, process.arch);
+    return JSON.parse(readFileSync(require.resolve(`${spec.pkg}/package.json`), "utf8")).version;
+  } catch {
+    return null;
+  }
+}
+
+/** This launcher package's own version. Published from `0.0.0-template`, which
+ *  the pipeline substitutes, so a `-template` here means a working copy. */
+const LAUNCHER_VERSION = (() => {
+  try {
+    return JSON.parse(
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
+    ).version;
+  } catch {
+    return "unknown";
+  }
+})();
+
 function fail(message) {
   console.error(`[${DISTRIBUTION.npmCommand}] ${message}`);
   process.exit(1);
@@ -95,6 +121,38 @@ function isExtractedBundleInside(tempDir, bundlePath) {
   }
 }
 
+// `--version` / `--rollback` answer and exit FIRST — before the payload is
+// resolved, before the store is prepared, before anything is spawned.
+//
+// Before the payload, because these are support commands and the moment you
+// need them is the moment the install is broken. A `--version` that refuses
+// with "platform payload is not installed" is useless exactly when someone is
+// trying to find out what state their machine is in, and a `--rollback` that
+// needs a healthy install cannot rescue an unhealthy one.
+//
+// Before the store, because preparing it would let `--version` apply a pending
+// update as a side effect of asking a question, and would let `--rollback` undo
+// a swap the same command had just performed.
+const launcherOwnCommand = launcherCommand(process.argv.slice(2));
+if (launcherOwnCommand !== null) {
+  process.exit(
+    runLauncherCommand(launcherOwnCommand, {
+      platform: process.platform,
+      home: homedir(),
+      env: process.env,
+      cacheName: DISTRIBUTION.cacheName,
+      // Null when npm's copy cannot be read. The store is the authority for what
+      // RUNS; the payload version is a second opinion these commands report
+      // alongside it, not something they depend on.
+      payloadVersion: readPayloadVersion(),
+      launcherVersion: LAUNCHER_VERSION,
+      log: (message) => {
+        console.log(message);
+      },
+    }),
+  );
+}
+
 let spec;
 try {
   spec = resolvePayloadSpec(process.platform, process.arch);
@@ -127,6 +185,17 @@ try {
 //                    lifecycle scripts on cached installs still self-heal.
 const payloadRoot = dirname(payloadPkgJson);
 const archivePath = join(payloadRoot, "app.tar.gz");
+// The version npm currently has on disk. On Windows this is what the store
+// seeds from; it goes STALE the moment the app updates itself, which is why the
+// store only ever seeds from it when it is genuinely newer than `current`.
+const payloadVersionForStore = (() => {
+  try {
+    return JSON.parse(readFileSync(payloadPkgJson, "utf8")).version;
+  } catch {
+    return "";
+  }
+})();
+
 let exePath;
 // The installed macOS `.app` bundle, when this is the macOS archive payload —
 // the anchor we hand to `open` so LaunchServices dedups. null on Windows
@@ -209,6 +278,61 @@ if (!existsSync(exePath)) {
   fail(`payload executable missing at: ${exePath}`);
 }
 
+// ── the versioned store (Windows npm channel) ─────────────────────────────
+//
+// Run from `<store>/current/...` rather than from the npm payload in place, so
+// an update can be staged beside the running copy and applied by moving a
+// pointer. `npm i -g` cannot do that: it renames the installed package aside
+// before unpacking and rolls that rename back only on a best-effort basis, so a
+// failed update over a locked, running exe can leave nothing installed at all.
+//
+// EVERY failure here falls back to `exePath` — the payload in place, exactly as
+// this launcher behaved before the store existed. A bug in the store must cost
+// a user their update, never their ability to start the app.
+/** The npm payload's own executable, captured before the store may replace
+ *  `exePath`, so a spawn failure can retreat to it instead of taking the whole
+ *  launcher down. */
+const payloadExePath = exePath;
+
+/**
+ * How long to watch a newly applied version before calling it started.
+ *
+ * Short on purpose. The launcher is a CLI: every millisecond here is a
+ * millisecond the user's terminal is held, and this only buys confidence
+ * against a process that dies straight away. The attempt counter in the store
+ * is what covers the slower failures.
+ */
+const HEALTH_WAIT_MS = 3000;
+
+/** Is the process we started still there? Signal 0 checks without delivering. */
+const stillRunning = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+let storeExePath = null;
+const storeVerbose = process.env.NISSY_STORE_DEBUG === "1";
+const storeLog = (message) => {
+  if (storeVerbose) console.error(`[${DISTRIBUTION.npmCommand}] ${message}`);
+};
+const staged = prepareStore({
+  platform: process.platform,
+  home: homedir(),
+  env: process.env,
+  cacheName: DISTRIBUTION.cacheName,
+  payloadVersion: payloadVersionForStore,
+  payloadRoot,
+  exeSegments: spec.exe,
+  log: storeLog,
+});
+if (staged !== null) {
+  exePath = staged.exePath;
+  storeExePath = staged.exePath;
+}
+
 // By default we launch the app detached and return immediately — `npx`/`nissy`
 // frees the terminal instead of streaming the app's stdio. The app writes its
 // own persistent log (electron-log → ~/Library/Logs/Nissy/main.log on macOS),
@@ -264,6 +388,22 @@ if (foreground) {
   child.on("error", (err) => {
     fail(`failed to spawn payload: ${err.message}`);
   });
+  // Same handshake as the detached path, but this process is sticking around
+  // anyway, so it can be a timer instead of a blocking wait. Without it,
+  // debugging with --foreground would spend an attempt on every run and
+  // eventually roll a perfectly good version back.
+  if (staged !== null && staged.awaitingConfirmation === true) {
+    setTimeout(() => {
+      confirmHealthyStart({
+        platform: process.platform,
+        home: homedir(),
+        env: process.env,
+        cacheName: DISTRIBUTION.cacheName,
+        confirm: child.exitCode === null && child.signalCode === null,
+        log: storeLog,
+      });
+    }, HEALTH_WAIT_MS).unref();
+  }
   child.on("exit", (code, signal) => {
     if (signal !== null) {
       // Re-raise the signal so the parent's exit reflects how the child died.
@@ -276,7 +416,34 @@ if (foreground) {
   // `open` exits as soon as it hands off to LaunchServices; the direct-exec
   // path needs the detach so this launcher can exit while the app keeps
   // running. Either way, don't tie the app's lifetime to this process.
-  const child = spawn(command, args, { detached: true, stdio: "ignore", env: childEnv });
+  let child;
+  try {
+    child = spawn(command, args, { detached: true, stdio: "ignore", env: childEnv });
+  } catch (err) {
+    // `spawn` throws synchronously for a malformed or unreadable executable
+    // (EFTYPE, ENOEXEC), so the "error" handler below never sees it and the
+    // launcher dies with a Node stack trace. Observed with a corrupt staged
+    // version. If we were running from the store, retreat to the npm payload
+    // rather than leaving the user with nothing; `pending` stays set, so the
+    // next launch rolls the bad version back.
+    if (storeExePath !== null && exePath !== payloadExePath) {
+      storeLog(`spawn failed from the store (${err.code || err.message}); using the npm payload`);
+      try {
+        // The retreat can throw too — the payload itself may be the thing that
+        // is broken. Then there is genuinely nothing left to run, and saying so
+        // beats a raw Node stack trace.
+        child = spawn(payloadExePath, args, { detached: true, stdio: "ignore", env: childEnv });
+      } catch (fallbackErr) {
+        fail(
+          `neither the staged version nor the npm payload could be started ` +
+            `(${err.code || err.message} / ${fallbackErr.code || fallbackErr.message}). ` +
+            `Reinstall with: npm i -g ${DISTRIBUTION.npmLauncherPackage}`,
+        );
+      }
+    } else {
+      fail(`failed to spawn payload: ${err.message}`);
+    }
+  }
   child.on("error", (err) => {
     fail(
       viaLaunchServices
@@ -285,4 +452,31 @@ if (foreground) {
     );
   });
   child.unref();
+
+  // The app is away. Two different jobs now, and conflating them is what made
+  // the first version of this wrong.
+  //
+  // A version we have already proven just needs its dead siblings dropped, and
+  // the launcher should get out of the way immediately.
+  //
+  // A version on trial needs evidence that it STARTED, and `spawn` returning a
+  // pid is not that — Windows creates the process before the loader has resolved
+  // a single import, so a build missing a DLL "spawns" perfectly and is gone a
+  // moment later. So wait, then ask whether it is still there. Cheap, and it
+  // catches the failure that actually happens. It is paid once per update, never
+  // on an ordinary launch.
+  //
+  // This is still the weak version of the handshake — see confirmHealthyStart.
+  const onTrial = staged !== null && staged.awaitingConfirmation === true;
+  if (onTrial) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, HEALTH_WAIT_MS);
+  }
+  confirmHealthyStart({
+    platform: process.platform,
+    home: homedir(),
+    env: process.env,
+    cacheName: DISTRIBUTION.cacheName,
+    confirm: onTrial && stillRunning(child.pid),
+    log: storeLog,
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nissyai/desktop",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "type": "module",
   "description": "Launcher for the Nissy desktop app. Resolves the host's app payload and spawns it. Run via `npx @nissyai/desktop`; a global install (`npm i -g @nissyai/desktop`) exposes the `nissy` command.",
   "license": "SEE LICENSE IN LICENSE",
@@ -20,8 +20,8 @@
     "src/"
   ],
   "optionalDependencies": {
-    "@nissyai/app-win32-x64": "0.2.36",
-    "@nissyai/app-darwin-arm64": "0.2.36",
-    "@nissyai/app-darwin-x64": "0.2.36"
+    "@nissyai/app-win32-x64": "0.2.38",
+    "@nissyai/app-darwin-arm64": "0.2.38",
+    "@nissyai/app-darwin-x64": "0.2.38"
   }
 }

package/src/cli.mjs

@@ -0,0 +1,169 @@
+// The launcher's own commands: `nissy --version` and `nissy --rollback`.
+//
+// Both exist for support rather than for users. The AUTOMATIC rollback — a
+// version that never confirms a start, after three attempts — is what protects
+// people, and it is in `store.mjs`. These two are for the conversation that
+// starts "it updated and now something is wrong", where the useful questions are
+// "which version is actually running?" and "put me back", and today the only way
+// to answer either is to read `store.log`.
+//
+// Kept out of `bin/nissy.mjs` because that file is a straight line — resolve the
+// payload, prepare the store, spawn — and a command that answers and exits does
+// not belong in the middle of it. Pure apart from the store it is handed, so the
+// tests do not need a real install.
+
+import {
+  compareVersions,
+  isCompleteVersion,
+  listVersions,
+  pointCurrentAt,
+  readCurrentVersion,
+  readPreviousVersion,
+  storeLayout,
+  versionDir,
+  clearPending,
+} from "./store.mjs";
+
+export const VERSION_FLAG = "--version";
+export const ROLLBACK_FLAG = "--rollback";
+
+/** Which command, if any, the argv asks for. */
+export function launcherCommand(argv) {
+  if (argv.includes(ROLLBACK_FLAG)) return "rollback";
+  if (argv.includes(VERSION_FLAG)) return "version";
+  return null;
+}
+
+/**
+ * What `--version` should print.
+ *
+ * Three versions, because they are genuinely three different things and the
+ * confusion between them is why this exists:
+ *
+ *   - the STORE's current version, which is what actually runs
+ *   - the npm PAYLOAD's version, which is what `npm i -g` last installed and
+ *     which goes stale the moment the app updates itself
+ *   - the LAUNCHER's own version
+ *
+ * A user reading "0.2.37" off `npm ls -g` while running 0.2.41 out of the store
+ * is the exact support call this is meant to shorten.
+ */
+export function describeVersions({ storeVersion, payloadVersion, launcherVersion, previousVersion }) {
+  const lines = [];
+  if (storeVersion !== null) {
+    lines.push(`running   ${storeVersion}`);
+  } else if (payloadVersion !== null) {
+    lines.push(`running   ${payloadVersion} (npm payload, no store yet)`);
+  } else {
+    // Neither readable. That IS the broken install this command exists to
+    // describe, so it reports what it found rather than refusing to answer.
+    lines.push("running   unknown - no store, and npm's payload could not be read");
+  }
+  if (storeVersion !== null && previousVersion !== null && previousVersion !== storeVersion) {
+    lines.push(`previous  ${previousVersion}`);
+  }
+  if (storeVersion !== null && payloadVersion !== null && payloadVersion !== storeVersion) {
+    // Not a warning. The store being AHEAD of npm is the normal steady state
+    // after a self-update, and saying so stops it looking like a fault.
+    lines.push(`npm has   ${payloadVersion}`);
+  }
+  if (storeVersion !== null && payloadVersion === null) {
+    lines.push("npm has   nothing readable - reinstall to repair the payload");
+  }
+  lines.push(`launcher  ${launcherVersion}`);
+  return lines.join("\n");
+}
+
+/**
+ * Decide what `--rollback` can do, without doing it.
+ *
+ * Separated from the action so every refusal is a value with a reason, and so
+ * the reasons are testable. A rollback that silently does nothing is worse than
+ * one that explains itself: the user reruns it, concludes the tool is broken,
+ * and reinstalls by hand — which is the thing this whole line of work exists to
+ * stop people having to do.
+ */
+export function planRollback({ currentVersion, previousVersion, versionExists }) {
+  if (currentVersion === null) {
+    return { ok: false, reason: "there is no versioned store yet, so there is nothing to roll back from" };
+  }
+  if (previousVersion === null) {
+    return { ok: false, reason: `${currentVersion} is the only version ever installed here` };
+  }
+  if (previousVersion === currentVersion) {
+    return { ok: false, reason: `${currentVersion} is already the previous version` };
+  }
+  if (compareVersions(previousVersion, currentVersion) > 0) {
+    // `previous` is NEWER. That happens the moment you roll back at all:
+    // pointing `current` at the old version demotes the new one to `previous`,
+    // so a second `--rollback` would put you straight back on the build you just
+    // escaped — while printing "rolled back", which is the opposite of true.
+    //
+    // A rollback only ever goes backwards. Going forwards is an update, and it
+    // has its own path.
+    return {
+      ok: false,
+      reason:
+        `${currentVersion} is already older than ${previousVersion}. ` +
+        `Rollback only goes backwards; use the app's update to move forward.`,
+    };
+  }
+  if (!versionExists(previousVersion)) {
+    // Pruned, or deleted by hand. Naming it matters: "reinstall to get it back"
+    // is actionable, "rollback failed" is not.
+    return {
+      ok: false,
+      reason:
+        `${previousVersion} is no longer on disk, so it cannot be restored. ` +
+        `Reinstall a specific version instead.`,
+    };
+  }
+  return { ok: true, from: currentVersion, to: previousVersion };
+}
+
+/**
+ * Run the command. Returns the process exit code.
+ *
+ * `log` rather than `console.log` directly so the tests can read what a user
+ * would see, which is the whole output of these commands.
+ */
+export function runLauncherCommand(
+  command,
+  { platform, home, env, cacheName, payloadVersion, launcherVersion, log },
+) {
+  const layout = storeLayout({ platform, home, env, ...(cacheName ? { cacheName } : {}) });
+
+  if (command === "version") {
+    log(
+      describeVersions({
+        storeVersion: readCurrentVersion(layout),
+        previousVersion: readPreviousVersion(layout),
+        payloadVersion,
+        launcherVersion,
+      }),
+    );
+    return 0;
+  }
+
+  const plan = planRollback({
+    currentVersion: readCurrentVersion(layout),
+    previousVersion: readPreviousVersion(layout),
+    versionExists: (version) =>
+      listVersions(layout).includes(version) && isCompleteVersion(versionDir(layout, version)),
+  });
+  if (!plan.ok) {
+    log(`cannot roll back: ${plan.reason}`);
+    return 1;
+  }
+  try {
+    pointCurrentAt(layout, plan.to);
+    // Whatever was pending was asking for the version we have just moved away
+    // from. Leaving it would let the next launch apply it again and undo this.
+    clearPending(layout);
+  } catch (err) {
+    log(`rollback failed: ${(err && err.message) || String(err)}`);
+    return 1;
+  }
+  log(`rolled back ${plan.from} -> ${plan.to}. Start Nissy again to use it.`);
+  return 0;
+}

package/src/resolve.d.mts

@@ -0,0 +1,14 @@
+// Types for the parts of the resolver the DESKTOP consumes.
+//
+// The launcher is plain ESM with JSDoc and has no build step. This declaration
+// exists so `apps/desktop`'s parity test can import the payload table and be
+// type-checked rather than silently typed `any` — which would let the test pass
+// while comparing `undefined` to `undefined`.
+
+/** Host key (`${platform}-${arch}`) → payload package + the executable within
+ *  it, as path segments. Mirrored by the app's `payloadExeSegments`; enforced by
+ *  `payload-exe-parity.test.ts`. */
+export declare const PAYLOADS: Record<
+  string,
+  { pkg: string; exe: readonly string[] }
+>;

package/src/store.d.mts

@@ -0,0 +1,38 @@
+// Types for the parts of the store the DESKTOP consumes.
+//
+// The launcher is plain ESM with JSDoc and has no build step; this declaration
+// exists so `apps/desktop`'s parity test can import `compareVersions` and be
+// type-checked rather than silently typed `any`. It deliberately declares only
+// what crosses that boundary, not the whole module — nothing else outside the
+// launcher should be importing from here.
+
+/** -1 / 0 / 1. Must agree with the app's `compareVersions`; enforced by
+ *  `apps/desktop/src/main/features/auto-update/version-parity.test.ts`. */
+export declare function compareVersions(a: string, b: string): number;
+
+/** Absolute paths of everything in the store. Mirrored by the app's
+ *  `npmStoreLayout`; enforced by `npm-store.parity.test.ts`. */
+export declare function storeLayout(input: {
+  platform: string;
+  home: string;
+  env: Record<string, string | undefined>;
+  cacheName?: string;
+}): {
+  root: string;
+  versionsDir: string;
+  currentLink: string;
+  previousLink: string;
+  pendingFile: string;
+  healthFile: string;
+  logFile: string;
+  lockDir: string;
+};
+
+/** Semver-ish, and free of anything that means something to a path. */
+export declare function isSafeVersion(version: string): boolean;
+
+/** Written last into a version directory; the only thing that makes it eligible. */
+export declare const SEED_COMPLETE_MARKER: string;
+
+/** Launches an applied version gets to prove it starts. */
+export declare const DEFAULT_TRIES: number;