@nissyai/desktop 0.1.0

package/bin/nissy.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+//
+// `nissy` launcher entry point (internal npx dev channel).
+//
+// Picks the payload package for the host platform/arch, finds where npm
+// installed it, and spawns the self-contained app executable inside it,
+// inheriting stdio and propagating the exit code / signal.
+
+import { execFileSync, spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  cacheRootSegments,
+  needsMacReinstall,
+  npxChannelEnv,
+  resolveLaunchCommand,
+  resolvePayloadSpec,
+  UnsupportedPlatformError,
+} from "../src/resolve.mjs";
+
+const require = createRequire(import.meta.url);
+
+function fail(message) {
+  console.error(`[nissy] ${message}`);
+  process.exit(1);
+}
+
+let spec;
+try {
+  spec = resolvePayloadSpec(process.platform, process.arch);
+} catch (err) {
+  if (err instanceof UnsupportedPlatformError) {
+    fail(`unsupported platform: ${err.key}`);
+  }
+  throw err;
+}
+
+let payloadPkgJson;
+try {
+  payloadPkgJson = require.resolve(`${spec.pkg}/package.json`);
+} catch {
+  fail(
+    `platform payload "${spec.pkg}" is not installed for ${spec.key}. ` +
+      `Reinstall so the matching optional dependency is fetched.`,
+  );
+}
+
+// Resolve the executable to launch. Two payload layouts:
+//   • app/         — Forge output copied verbatim (Windows). Run in place.
+//   • app.tar.gz   — symlink-preserving archive (macOS; npm pack would strip the
+//                    .app's framework symlinks). INSTALL it into ~/Applications
+//                    — a standard, Spotlight-indexed location — so Nissy shows
+//                    in Spotlight / Launchpad / Finder and carries its Dock
+//                    icon, rather than running hidden from a per-user cache.
+//                    Refreshed in place when the payload version changes. Done
+//                    here (not a postinstall hook) so package managers that skip
+//                    lifecycle scripts on cached installs still self-heal.
+const payloadRoot = dirname(payloadPkgJson);
+const archivePath = join(payloadRoot, "app.tar.gz");
+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
+// (run-in-place), where we exec the binary directly.
+let macBundlePath = null;
+if (existsSync(join(payloadRoot, "app"))) {
+  exePath = join(payloadRoot, ...spec.exe);
+} else if (existsSync(archivePath)) {
+  const { version } = JSON.parse(readFileSync(payloadPkgJson, "utf8"));
+  const appsDir = join(homedir(), "Applications");
+  const bundleName = spec.exe[1]; // e.g. "Nissy.app" (spec.exe[0] is "app")
+  const installedApp = join(appsDir, bundleName);
+  macBundlePath = installedApp;
+  // The exe inside the installed bundle (drop the payload's leading "app/").
+  exePath = join(appsDir, ...spec.exe.slice(1));
+  const cacheRoot = join(
+    ...cacheRootSegments({ platform: process.platform, home: homedir(), env: process.env }),
+  );
+  const markerPath = join(cacheRoot, "applications-darwin.version");
+  const markerVersion = existsSync(markerPath)
+    ? readFileSync(markerPath, "utf8").trim()
+    : null;
+
+  if (needsMacReinstall({ markerVersion, payloadVersion: version, exeExists: existsSync(exePath) })) {
+    const tmp = `${installedApp}.tmp.${process.pid}`;
+    try {
+      rmSync(tmp, { recursive: true, force: true });
+      mkdirSync(tmp, { recursive: true });
+      execFileSync("tar", ["-xzf", archivePath, "-C", tmp], { stdio: "inherit" });
+      const tmpApp = join(tmp, bundleName);
+      if (!existsSync(tmpApp)) {
+        rmSync(tmp, { recursive: true, force: true });
+        fail(`payload archive ${archivePath} did not contain ${bundleName}`);
+      }
+      mkdirSync(appsDir, { recursive: true });
+      // Swap: move any existing install aside, rename the new one into place,
+      // then best-effort remove the old. RENAMING the old bundle (rather than
+      // deleting it) keeps a currently-running instance's mapped files valid
+      // until it quits; the new version is used on next launch.
+      const old = `${installedApp}.old.${process.pid}`;
+      rmSync(old, { recursive: true, force: true });
+      if (existsSync(installedApp)) renameSync(installedApp, old);
+      renameSync(tmpApp, installedApp);
+      rmSync(tmp, { recursive: true, force: true });
+      rmSync(old, { recursive: true, force: true });
+      mkdirSync(dirname(markerPath), { recursive: true });
+      writeFileSync(markerPath, version);
+      // Best-effort: index the new bundle now so Spotlight/Launchpad pick it up
+      // without waiting for the periodic scan. Never block launch.
+      try {
+        execFileSync("/usr/bin/mdimport", [installedApp], { stdio: "ignore" });
+      } catch {
+        // ignore — Spotlight indexes ~/Applications on its own schedule too
+      }
+    } catch (err) {
+      rmSync(tmp, { recursive: true, force: true });
+      if (!existsSync(exePath)) {
+        fail(`failed to install ${installedApp}: ${err.message}`);
+      }
+    }
+  }
+
+  // Best-effort: reclaim space from the OLD version-keyed cache layout earlier
+  // launcher versions used (~140 MB each). Never block launch.
+  try {
+    for (const entry of readdirSync(cacheRoot)) {
+      if (entry.startsWith("nissy-app-darwin-")) {
+        rmSync(join(cacheRoot, entry), { recursive: true, force: true });
+      }
+    }
+  } catch {
+    // ignore — cleanup is non-essential
+  }
+} else {
+  fail(`payload "${spec.pkg}" contains neither app/ nor app.tar.gz`);
+}
+
+if (!existsSync(exePath)) {
+  fail(`payload executable missing at: ${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),
+// so dropping stdio here loses nothing. Pass --foreground to stay attached and
+// mirror the app's stdio + exit code, which is what you want when debugging.
+const forwardedArgs = process.argv.slice(2).filter((a) => a !== "--foreground");
+const foreground = forwardedArgs.length !== process.argv.slice(2).length;
+
+// On macOS, launch through `/usr/bin/open <bundle>` so LaunchServices enforces
+// single-instance: a `nissy`/`npx` run while Nissy is already up just activates
+// the running instance instead of spawning a second mascot. Direct-exec of the
+// inner binary (Windows, or `--foreground` debugging on macOS) bypasses that OS
+// dedup and leans solely on Electron's userData lock — which fails open after a
+// stale-lock-leaving crash. See resolveLaunchCommand for the full rationale.
+const { command, args, viaLaunchServices } = resolveLaunchCommand({
+  platform: process.platform,
+  bundlePath: macBundlePath,
+  exePath,
+  foreground,
+  forwardedArgs,
+});
+
+// Stamp the spawned app with this channel + the STABLE launcher command
+// (absolute node + this script). On Windows the app reads the channel marker to
+// pick its autostart/update strategy; on macOS the channel is platform-derived
+// (and `open` launches via LaunchServices, which does NOT inherit this env
+// anyway), so the stamp is a harmless no-op there.
+const childEnv = {
+  ...process.env,
+  ...npxChannelEnv(process.execPath, fileURLToPath(import.meta.url)),
+};
+
+if (foreground) {
+  const child = spawn(command, args, { stdio: "inherit", env: childEnv });
+  child.on("error", (err) => {
+    fail(`failed to spawn payload: ${err.message}`);
+  });
+  child.on("exit", (code, signal) => {
+    if (signal !== null) {
+      // Re-raise the signal so the parent's exit reflects how the child died.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+} else {
+  // `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 });
+  child.on("error", (err) => {
+    fail(
+      viaLaunchServices
+        ? `failed to launch via 'open': ${err.message}`
+        : `failed to spawn payload: ${err.message}`,
+    );
+  });
+  child.unref();
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@nissyai/desktop",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Launcher for the Nissy desktop app (internal npx dev channel). 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",
+  "author": {
+    "name": "Cleverbit",
+    "email": "hello@cleverbit.software"
+  },
+  "homepage": "https://nissy.ai",
+  "bin": {
+    "nissy": "bin/nissy.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "optionalDependencies": {
+    "@nissyai/app-win32-x64": "0.1.0",
+    "@nissyai/app-darwin-arm64": "0.1.0",
+    "@nissyai/app-darwin-x64": "0.1.0"
+  }
+}

package/src/resolve.mjs

@@ -0,0 +1,181 @@
+// Pure platform → payload mapping for the `nissy` launcher.
+//
+// No IO here so it is trivially unit-testable. The bin entry
+// (../bin/nissy.mjs) layers `require.resolve` + `spawn` on top.
+//
+// The Electron Forge `package` output is self-contained (it bundles
+// Electron), so each payload exposes a single executable we spawn
+// directly — there is no dependency on the `electron` npm package.
+
+/** Error thrown when the host platform/arch has no payload mapping. */
+export class UnsupportedPlatformError extends Error {
+  /** @param {string} key host key, e.g. "linux-x64" */
+  constructor(key) {
+    super(`unsupported platform: ${key}`);
+    this.name = "UnsupportedPlatformError";
+    this.key = key;
+  }
+}
+
+/**
+ * Host key (`${platform}-${arch}`) → payload package name + the executable
+ * within it, expressed as path segments (joined with the OS separator at
+ * the call site so this stays platform-neutral and testable).
+ *
+ * @type {Record<string, { pkg: string, exe: readonly string[] }>}
+ */
+export const PAYLOADS = {
+  "win32-x64": {
+    pkg: "@nissyai/app-win32-x64",
+    exe: ["app", "nissy.exe"],
+  },
+  "darwin-arm64": {
+    pkg: "@nissyai/app-darwin-arm64",
+    exe: ["app", "Nissy.app", "Contents", "MacOS", "nissy"],
+  },
+  "darwin-x64": {
+    pkg: "@nissyai/app-darwin-x64",
+    exe: ["app", "Nissy.app", "Contents", "MacOS", "nissy"],
+  },
+};
+
+/**
+ * Resolve the payload spec for a host platform/arch.
+ * @param {NodeJS.Platform | string} platform
+ * @param {string} arch
+ * @returns {{ key: string, pkg: string, exe: readonly string[] }}
+ * @throws {UnsupportedPlatformError} when no mapping exists
+ */
+export function resolvePayloadSpec(platform, arch) {
+  const key = `${platform}-${arch}`;
+  const spec = PAYLOADS[key];
+  if (spec === undefined) {
+    throw new UnsupportedPlatformError(key);
+  }
+  return { key, pkg: spec.pkg, exe: spec.exe };
+}
+
+/**
+ * Path segments for the per-user cache root where a payload that ships as an
+ * archive (macOS — npm pack strips the .app's framework symlinks) is extracted
+ * on first run. Pure (env injected) so it stays unit-testable; the caller joins
+ * with the OS separator.
+ *
+ * @param {{ platform: NodeJS.Platform | string, home: string, env: Record<string, string | undefined> }} host
+ * @returns {string[]} path segments of the cache root
+ */
+export function cacheRootSegments({ platform, home, env }) {
+  if (platform === "darwin") return [home, "Library", "Caches", "nissy"];
+  if (platform === "win32") {
+    return [env.LOCALAPPDATA || env.TEMP || home, "nissy", "Cache"];
+  }
+  return env.XDG_CACHE_HOME ? [env.XDG_CACHE_HOME, "nissy"] : [home, ".cache", "nissy"];
+}
+
+/**
+ * Filesystem-safe, version-pinned cache key for a payload package, e.g.
+ * ("@nissyai/app-darwin-x64", "1.2.3") → "nissyai-app-darwin-x64@1.2.3". Version
+ * pinning means a new app version extracts to a fresh dir (no stale binaries).
+ *
+ * @param {string} pkg payload package name
+ * @param {string} version
+ * @returns {string}
+ */
+export function payloadCacheKey(pkg, version) {
+  const safe = pkg.replace(/^@/, "").replace(/\//g, "-");
+  return `${safe}@${version}`;
+}
+
+/**
+ * Given the entry names in the cache root and the current cache key, return the
+ * stale extracted-payload dirs to prune (older versions of the SAME payload).
+ * Keeps the current version; ignores unrelated dirs and in-flight `.tmp.<pid>`
+ * extraction dirs (a concurrent first-run may still own those). Pure so the
+ * keep/prune decision is unit-testable; the caller does the filesystem removal.
+ *
+ * @param {string[]} entries dir names directly under the cache root
+ * @param {string} currentKey the current `payloadCacheKey(pkg, version)`
+ * @returns {string[]} entry names safe to remove
+ */
+export function stalePayloadCaches(entries, currentKey) {
+  const at = currentKey.lastIndexOf("@");
+  if (at <= 0) return [];
+  const pkgPrefix = currentKey.slice(0, at + 1); // e.g. "nissyai-app-darwin-x64@"
+  return entries.filter(
+    (name) =>
+      name !== currentKey &&
+      name.startsWith(pkgPrefix) &&
+      !name.includes(".tmp."),
+  );
+}
+
+/**
+ * Environment the launcher stamps on the spawned app so it can tell it was
+ * started via this channel (vs the native Velopack install) and knows the
+ * STABLE launcher command to register for launch-at-login. A macOS LaunchAgent
+ * must point at an absolute node + script, NOT the version-keyed payload cache
+ * exe (which is pruned on update). Pure so the mapping is unit-testable.
+ *
+ * @param {string} nodePath absolute path to the node binary running the launcher (`process.execPath`)
+ * @param {string} launcherScript absolute path to this launcher script
+ * @returns {{ NISSY_CHANNEL: string, NISSY_LAUNCHER_NODE: string, NISSY_LAUNCHER_SCRIPT: string }}
+ */
+export function npxChannelEnv(nodePath, launcherScript) {
+  return {
+    NISSY_CHANNEL: "npx",
+    NISSY_LAUNCHER_NODE: nodePath,
+    NISSY_LAUNCHER_SCRIPT: launcherScript,
+  };
+}
+
+/**
+ * Decide HOW to launch the resolved payload — the command + argv to spawn.
+ *
+ * On macOS we go through `/usr/bin/open <bundle>` so that **LaunchServices**
+ * enforces its single-instance rule: launching an app that's already running
+ * just activates the existing instance instead of spawning a second process.
+ * Exec'ing the inner Mach-O binary directly (`…/Contents/MacOS/nissy`, the
+ * historical path) bypasses that OS-level dedup entirely — leaving Electron's
+ * userData `requestSingleInstanceLock()` as the *only* guard, which fails open
+ * when a prior instance crashed and left a stale `SingletonLock` (this is how
+ * two mascots ended up running at once). Note: plain `open` — NOT `open -n`,
+ * which would FORCE a new instance, the opposite of what we want.
+ *
+ * `--foreground` (a debugging mode that mirrors the app's stdio + exit code)
+ * keeps the direct-exec path, since `open` detaches and can't stream stdio.
+ * Windows has no `open` equivalent here and runs the payload in place, so it
+ * also keeps the direct-exec path.
+ *
+ * Pure (no IO) so the decision is unit-testable; the caller does the spawn.
+ *
+ * @param {{
+ *   platform: NodeJS.Platform | string,
+ *   bundlePath: string | null,
+ *   exePath: string,
+ *   foreground: boolean,
+ *   forwardedArgs: readonly string[],
+ * }} input bundlePath is the installed `.app` (macOS only; null elsewhere).
+ * @returns {{ command: string, args: string[], viaLaunchServices: boolean }}
+ */
+export function resolveLaunchCommand({ platform, bundlePath, exePath, foreground, forwardedArgs }) {
+  if (platform === "darwin" && !foreground && bundlePath !== null) {
+    const args = [bundlePath];
+    // `open` forwards extra argv to the app only after a `--args` separator.
+    if (forwardedArgs.length > 0) args.push("--args", ...forwardedArgs);
+    return { command: "/usr/bin/open", args, viaLaunchServices: true };
+  }
+  return { command: exePath, args: [...forwardedArgs], viaLaunchServices: false };
+}
+
+/**
+ * Whether the macOS ~/Applications install needs (re)writing: when the recorded
+ * install-version marker doesn't match the payload version, or the installed
+ * bundle's executable is missing. Pure so the decision is unit-testable; the
+ * launcher does the filesystem work.
+ *
+ * @param {{ markerVersion: string | null, payloadVersion: string, exeExists: boolean }} input
+ * @returns {boolean}
+ */
+export function needsMacReinstall({ markerVersion, payloadVersion, exeExists }) {
+  return !exeExists || markerVersion !== payloadVersion;
+}