@smartspec/cli 0.0.0-stage → 0.1.0

package/lib/install.js

@@ -0,0 +1,118 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+import { access, constants, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { APP_ID, APP_NAME, REPOSITORY } from './platform.js';
+
+// Installing the app, for the smartspec command's install: the latest release's build for this
+// Mac, as the app's own updater finds it (latest-mac.yml lists each zip with its SHA-512), checked
+// and unpacked into Applications. Tests point it at a stand-in release (SMARTSPEC_DOWNLOADS) and
+// another folder (SMARTSPEC_INSTALL_DIR).
+
+const run = promisify(execFile);
+
+export const downloadBase = (env = process.env) => (env.SMARTSPEC_DOWNLOADS ?? `https://github.com/${REPOSITORY}/releases/latest/download`).replace(/\/$/, '');
+
+// The release's version and files, from latest-mac.yml (the few lines electron-builder writes).
+export function parseLatest(text) {
+  const files = [];
+  let version = null;
+  for (const line of text.split(/\r?\n/)) {
+    const field = line.match(/^\s*(-\s+)?(\w+):\s*'?([^']*?)'?\s*$/);
+    if (!field) continue;
+    const [, item, key, value] = field;
+    if (!item && !line.startsWith(' ') && key === 'version') version = value;
+    else if (item && key === 'url') files.push({ url: value });
+    else if (line.startsWith('    ') && files.length && (key === 'sha512' || key === 'size')) files.at(-1)[key] = key === 'size' ? Number(value) : value;
+  }
+  return { version, files };
+}
+
+// The zip for this Mac: arm64 or x64 in its name.
+export function zipFor(files, arch = process.arch) {
+  return files.find((f) => f.url.endsWith('.zip') && f.url.includes(`-mac-${arch}`)) ?? null;
+}
+
+// Where the app goes: Applications if the user can write there, else ~/Applications.
+export async function installDir({ env = process.env, home = os.homedir() } = {}) {
+  if (env.SMARTSPEC_INSTALL_DIR) return path.resolve(env.SMARTSPEC_INSTALL_DIR);
+  try {
+    await access('/Applications', constants.W_OK);
+    return '/Applications';
+  } catch {
+    return path.join(home, 'Applications');
+  }
+}
+
+async function get(url, signal) {
+  const res = await fetch(url, { redirect: 'follow', signal });
+  if (!res.ok) throw new Error(`Couldn’t download ${url} (HTTP ${res.status}).`);
+  return res;
+}
+
+// What the latest release offers this Mac: { version, zip } (zip null if there's no build for it).
+export async function latestRelease({ env = process.env, arch = process.arch } = {}) {
+  const { version, files } = parseLatest(await (await get(`${downloadBase(env)}/latest-mac.yml`)).text());
+  if (!version) throw new Error('The latest release doesn’t say its version.');
+  return { version, zip: zipFor(files, arch) };
+}
+
+// Downloads and checks the zip, unpacks it, and puts the app in `dir` (replacing one there). Calls
+// `progress(received, total)` as it downloads. Resolves to the app's path.
+export async function installRelease(zip, dir, { env = process.env, progress = () => {} } = {}) {
+  const work = await mkdtemp(path.join(os.tmpdir(), 'smartspec-install-'));
+  try {
+    const file = path.join(work, path.basename(zip.url));
+    const res = await get(`${downloadBase(env)}/${zip.url}`);
+    const total = Number(res.headers.get('content-length')) || zip.size || null;
+    const hash = createHash('sha512');
+    let received = 0;
+    const tap = new Transform({
+      transform(chunk, _encoding, done) {
+        hash.update(chunk);
+        received += chunk.length;
+        progress(received, total);
+        done(null, chunk);
+      },
+    });
+    await pipeline(Readable.fromWeb(res.body), tap, createWriteStream(file));
+    if (hash.digest('base64') !== zip.sha512) throw new Error(`The download of ${zip.url} didn’t match the release’s checksum, so it wasn’t used.`);
+
+    // ditto keeps the app's code signature, permissions and links intact.
+    const unpacked = path.join(work, 'unpacked');
+    await run('ditto', ['-x', '-k', file, unpacked]);
+    const built = path.join(unpacked, `${APP_NAME}.app`);
+    if (!existsSync(built)) throw new Error(`${zip.url} doesn’t contain ${APP_NAME}.app.`);
+
+    await mkdir(dir, { recursive: true });
+    const target = path.join(dir, `${APP_NAME}.app`);
+    await rm(target, { recursive: true, force: true });
+    try {
+      await rename(built, target);
+    } catch {
+      await run('ditto', [built, target]); // another disk: copied instead
+    }
+    return target;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+// Whether the app is open (macOS knows it by its ID), and quitting it.
+export async function appRunning() {
+  try {
+    const { stdout } = await run('osascript', ['-e', `application id "${APP_ID}" is running`]);
+    return stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+export async function quitApp() {
+  await run('osascript', ['-e', `tell application id "${APP_ID}" to quit`]);
+  for (let i = 0; i < 40 && (await appRunning()); i++) await new Promise((r) => setTimeout(r, 250));
+}

package/lib/launch.js

@@ -0,0 +1,96 @@
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { APP_ID, APP_NAME, DOWNLOAD_PAGE, appEnv, mcpUrl, ownApp, userDataDir } from './platform.js';
+
+// Makes sure the app is running with its MCP server up, opening it if not. A running app is
+// shared: every launcher connects to the same one, and it stays open when they disconnect. The
+// app isn't downloaded from here: the user installs it from the project's releases, or with `smartspec install`.
+
+const run = promisify(execFile);
+
+const START_TIMEOUT_MS = 90 * 1000;
+const POLL_MS = 400;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// The token the app's MCP server expects. It's kept in the app's data folder, so it's only
+// readable by the user (and only exists once the app has run).
+export function readToken({ env = process.env } = {}) {
+  try {
+    return readFileSync(path.join(userDataDir({ env }), 'mcp-token'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+// 'up' when the server answers with this token; 'down' when nothing is listening; 'locked' when
+// something answers but refuses the token (it may not have been written yet).
+export async function probe({ env = process.env } = {}) {
+  const token = readToken({ env });
+  try {
+    // The server only takes POST, so a GET that gets past the token check answers 405.
+    const res = await fetch(mcpUrl(env), { headers: token ? { authorization: `Bearer ${token}` } : {} });
+    await res.body?.cancel();
+    return res.status === 405 ? 'up' : 'locked';
+  } catch {
+    return 'down';
+  }
+}
+
+export class NotInstalled extends Error {
+  constructor() {
+    super(`${APP_NAME} isn't installed on this computer. Tell the user to download it from ${DOWNLOAD_PAGE}, open it once, then try again.`);
+  }
+}
+
+export async function ensureRunning({ env = process.env, log = () => {}, execPath = process.execPath, platform = process.platform } = {}) {
+  if ((await probe({ env })) === 'up') return false;
+  await openApp({ env, log, execPath, platform });
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if ((await probe({ env })) === 'up') return true; // started by this launcher
+    await sleep(POLL_MS);
+  }
+  throw new Error(`${APP_NAME} didn’t start in time. Open it yourself, then try again.`);
+}
+
+// Opens the app: the one given by SMARTSPEC_APP, else the app this launcher is part of, else the
+// installed app, which macOS finds by its ID wherever it is.
+async function openApp({ env, log, execPath, platform }) {
+  const override = env.SMARTSPEC_APP;
+  if (override) {
+    log(`Opening ${override}…`);
+    return start(appCommand(path.resolve(override)), appEnv(env));
+  }
+  if (platform !== 'darwin') throw new Error(`${APP_NAME} runs on macOS for now.`);
+  const own = ownApp(execPath);
+  log(`Opening ${own ?? APP_NAME}…`);
+  try {
+    await run('open', own ? [own] : ['-b', APP_ID], { env: appEnv(env) });
+  } catch {
+    throw new NotInstalled();
+  }
+}
+
+// How to start an app given by path: a macOS app bundle, a project folder (run with its own
+// Electron, as in development: the nearest one installed, which in a workspace may be above it)
+// or an executable.
+export function appCommand(target) {
+  if (target.endsWith('.app')) return ['open', [target]];
+  if (existsSync(target) && statSync(target).isDirectory()) {
+    const name = process.platform === 'win32' ? 'electron.cmd' : 'electron';
+    for (let dir = target; ; dir = path.dirname(dir)) {
+      const electron = path.join(dir, 'node_modules', '.bin', name);
+      if (existsSync(electron) || dir === path.dirname(dir)) return [electron, [target]];
+    }
+  }
+  return [target, []];
+}
+
+// Detached, so the app outlives this launcher and the AI app that started it.
+function start([command, args], env) {
+  const child = spawn(command, args, { detached: true, stdio: 'ignore', env });
+  child.on('error', () => {}); // reported as a timeout by ensureRunning
+  child.unref();
+}

package/lib/platform.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Where things are on this computer. Everything here can be overridden with environment
+// variables, which development and tests use to keep away from the user's real app and data:
+//   SMARTSPEC_APP        the app to open: a SmartSpec.app, an executable, or a project
+//                       folder (run with its own Electron), instead of the installed one
+//   SMARTSPEC_USER_DATA  the app's data folder (passed on to a project-folder app)
+//   SMARTSPEC_PORT       the port the app's MCP server listens on (likewise)
+
+export const APP_NAME = 'SmartSpec';
+export const APP_ID = 'com.tw050x.smartspec';
+export const REPOSITORY = 'tw050x/smartspec';
+export const DOWNLOAD_PAGE = 'https://github.com/tw050x/smartspec/releases/latest';
+export const DEFAULT_PORT = 47825;
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+export const port = (env = process.env) => Number(env.SMARTSPEC_PORT) || DEFAULT_PORT;
+export const mcpUrl = (env = process.env) => `http://127.0.0.1:${port(env)}/mcp`;
+
+// The folder Electron gives the app for its data (it holds the MCP server's token).
+export function userDataDir({ env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.SMARTSPEC_USER_DATA) return path.resolve(env.SMARTSPEC_USER_DATA);
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', APP_NAME);
+  if (platform === 'win32') return path.join(env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), APP_NAME);
+  return path.join(env.XDG_CONFIG_HOME ?? path.join(home, '.config'), APP_NAME);
+}
+
+// The app bundle this launcher runs from, when it's the copy inside the app (run by the app's own
+// executable, …/SmartSpec.app/Contents/MacOS/SmartSpec, as Node); null when it runs from npm.
+export function ownApp(execPath = process.execPath) {
+  const match = execPath.match(/^(.*?\.app)\/Contents\/MacOS\/[^/]+$/);
+  return match ? match[1] : null;
+}
+
+// The environment for opening the app: without ELECTRON_RUN_AS_NODE, which runs this launcher
+// inside the app as Node and would make an Electron app it starts run as Node too.
+export function appEnv(env = process.env) {
+  const { ELECTRON_RUN_AS_NODE, ...rest } = env;
+  return rest;
+}